Make your product agent-ready
Tool Design
Principles for defining tools that agents select correctly and execute reliably
Last verified 2026-09-24
Summary
Tool Design is the behavior contract for model-callable actions across frameworks. Use it when defining how an agent chooses, validates, executes, and interprets a tool, whether the tool is backed by an , , database, server, or local function.
- Owns: names, descriptions, input/output schemas, safety annotations, budget, curation, and portability.
- Does not own: HTTP/OpenAPI contracts; see API Surface. MCP server lifecycle and transports; see MCP Servers.
- Agent-ready means: the model can pick the right tool, pass valid parameters, understand the result, and recover from failure without hidden product knowledge.
Start Here
- Naming and Descriptions - Write tool names and descriptions that disambiguate intent.
- Schemas - Keep inputs and outputs typed, constrained, and model-legible.
- Idempotency and Safety - Separate read, write, and destructive operations; annotation presets and the draft-then-confirm pattern.
- Human Approval - The approval contract a tool exposes so an agent can request, wait for, and confirm human sign-off.
- Tool Curation - Expose the smallest useful tool set per task or agent; sprawl prevention and dynamic selection.
- Cross-Framework Portability - Define once and adapt to MCP, AI SDK, OpenAI, and other runtimes.
- Token Budget - Keep tool output useful without flooding context.
- Anti-Patterns - Spot vague, unsafe, or expensive tool definitions.