Designing tools for agents

Tool quality drives agent quality. Design tools for a model reader: clear names, rich descriptions, small focused inputs and concise outputs.

Evolving: the basics hold, details shift. Reviewed 17 Oct 2026.

Key ideas

• Build tools around user tasks (search_customers, get_order) rather than mirroring every API endpoint.
• Descriptions should say when to use the tool, what it returns and its limits; include an example.
• Return human-readable fields and stable IDs; paginate and truncate large results with a hint to narrow the query.
• Make errors actionable: what went wrong and what argument to change.
• Keep the tool count per agent manageable; use tool search or sub-agents when there are many.
• Separate read tools from write tools and require confirmation for destructive actions.

Common mistakes

• Returning raw JSON blobs of thousands of tokens that flood the context.

Go deeper

• Writing tools for agents (Anthropic)