Skip to main content

​
Tool Authorization

Tool authorization creates a signed manifest of tools your agent is authorized to use. Every attestation can then verify that only authorized tools were used.

​
Why Tool Authorization?

AI agents are powerful because of the tools they can use. But this power needs boundaries:
  • Prevent capability creep — Detect when an agent uses tools it shouldn’t
  • Audit trail — Know exactly what tools were used for each action
  • Compliance — Prove your agent operates within defined boundaries
  • Security — Detect if an agent has been modified to use unauthorized tools

​
Setting Up a Tool Manifest

Register the tools your agent is authorized to use: 
from treeship_sdk import Treeship

ts = Treeship(api_key='your-key')

# Register authorized tools
ts.set_tool_manifest(
    agent="my-agent",
    tools=[
        "read_file",
        "write_file",
        "search_web",
        "send_email",
        "query_database"
    ],
    tool_descriptions={
        "send_email": "Send email to approved domains only",
        "query_database": "Read-only access to customer DB"
    }
)
The manifest is:
  • Signed by Treeship’s key for integrity
  • Hashed for quick verification
  • Timestamped to track changes

​
Verifying Tool Usage

When creating attestations, include the tools that were used: 
result = ts.attest(
    action="Sent weekly report to user@example.com",
    tools_used=["read_file", "send_email"]
)

if result.tools_authorized:
    print("✓ All tools were authorized")
else:
    print("⚠ Unauthorized tool usage detected!")

​
Standalone Verification

You can also verify tools without creating an attestation: 
# Check if a set of tools is authorized
result = ts.verify_tools(
    agent="my-agent",
    tools_used=["read_file", "delete_database"]
)

print(result)
# {
#   "verified": False,
#   "authorized_tools": ["read_file"],
#   "unauthorized_tools": ["delete_database"],
#   "manifest_hash": "abc123..."
# }

​
API Reference

​
Create/Update Manifest

curl -X POST https://api.treeship.dev/v1/identity/my-agent/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["read_file", "write_file", "send_email"],
    "tool_descriptions": {
      "send_email": "Approved domains only"
    }
  }'

​
Get Manifest

curl https://api.treeship.dev/v1/identity/my-agent/tools

​
Verify Tools

curl -X POST "https://api.treeship.dev/v1/identity/my-agent/verify-tools?tools_used=read_file&tools_used=send_email"

​
Manifest Response

{
  "agent_slug": "my-agent",
  "tool_manifest_hash": "e3b0c442...",
  "tools": ["read_file", "send_email", "write_file"],
  "signature": "base64-signature...",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

​
Best Practices

Principle of Least Privilege

Only authorize the minimum tools needed for the agent’s function.

Review Regularly

Audit and update tool manifests as agent capabilities change.

Include in CI/CD

Update manifests automatically when deploying agent changes.

Alert on Violations

Set up monitoring to alert when tools_authorized: false.

​
Use Cases

​
Financial Agents

ts.set_tool_manifest(
    agent="payment-processor",
    tools=[
        "verify_identity",
        "check_balance",
        "initiate_transfer",
        "send_confirmation"
    ]
)
# Agent cannot: delete_account, modify_limits, access_admin_panel

​
Customer Support

ts.set_tool_manifest(
    agent="support-bot",
    tools=[
        "search_knowledge_base",
        "create_ticket",
        "send_email",
        "escalate_to_human"
    ]
)
# Agent cannot: access_billing, modify_account, refund_payment

​
Code Assistant

ts.set_tool_manifest(
    agent="code-assistant",
    tools=[
        "read_file",
        "write_file",
        "run_tests",
        "search_codebase"
    ]
)
# Agent cannot: deploy_production, access_secrets, modify_infra