Skip to main content
ToolDefinition is the stable callable contract for Agent tools. The current runtime treats tools as first-class runtime objects rather than prompt-only suggestions.

​
Current shape

Each tool definition carries:
  • name
  • description
  • inputSchema
  • ownership
  • permissionPolicy

​
Ownership

Current ownership values:
  • managed
  • mcp
  • custom
Meaning:
  • managed
    • runtime-owned capability
  • mcp
    • capability exposed through MCP
  • custom
    • capability that requires user-side or app-side fulfillment
This ownership split matters because not all tools are executed the same way.

​
Permission policies

Current permission policies:
  • always_allow
  • always_ask
These follow the Anthropic naming directly. They should be read as runtime policy, not UI phrasing.

​
Custom tools

Custom tools are special because they do not complete inside the same bounded harness run. Instead:
  1. the harness emits agent.custom_tool_use
  2. the session pauses with requires_action
  3. a later user.custom_tool_result event resumes the session
That keeps custom-tool pausing inside the session model rather than inventing a separate out-of-band workflow.

​
What does not belong here

Tool definitions are not:
  • session scheduling
  • shared chat routing
  • work publication
  • environment configuration
Those are separate seams.