Agent Tools

Agent Tools let a model act through typed, testable capabilities. Choose where each capability should run.

Tool type	Runs in	Best for
`@tool`	Agent server	Business logic and provider calls
`@client_tool`	Browser, desktop, or mobile host	UI and device capabilities
MCP tool	Remote MCP server	External capability servers

Discovery properties

Property	Rule
Location	`tools/<name>.py`
Export	One callable matching the filename
Description	Docstring or decorator description
Arguments	Structured values
Results	Structured values, optionally validated by Pydantic
Credentials	Resolve through `context.credentials`, never tool arguments

Run typed capabilities inside the agent server.

Suspend the agent while a connected client performs local work.

Protect every tool call or one risky operation found at runtime.

Connect the agent to tools hosted by an MCP server.

Need	Use
Every call requires permission	`@require_human_approval`
Evaluation finds one risky operation	`request_human_approval(...)`
Remote operation requires permission	Approval policy on the MCP client

Approval resumes the exact suspended task without replaying earlier work.