Tool-Calling Design
A tool is a contract between a deterministic system and a non-deterministic agent. Tools written like ordinary APIs underperform; tools designed for how agents actually reason, and tuned against evals, are what make an agent effective.
When you write a normal function, both sides are deterministic: getWeather("NYC") behaves identically every call. A tool is different, the caller is an agent that might call it, answer from memory, ask a clarifying question, or misuse it. That means you cannot just expose your REST endpoints and hope; you must design the tool surface for an agent's strengths and failure modes. Source: Anthropic, https://www.anthropic.com/engineering/writing-tools-for-agents, 2026-05-31
Principles
- Choose the right tools, and the right number. Consolidate workflows instead of wrapping every API endpoint one-to-one. Fewer, higher-level tools that match real tasks beat a sprawling catalog the agent has to assemble.
- Namespace for clear boundaries. Prefix and group tools (
asana_search,slack_send) so the agent can tell overlapping capabilities apart. - Return meaningful context, not raw dumps. Send back what helps the next decision. This is depth-of-context thinking applied to tool returns.
- Optimize for token efficiency. Responses share the attention budget; paginate, truncate, and let the agent request detail rather than flooding the window.
- Prompt-engineer the descriptions. The tool's name, description, and parameter docs are prompt surface. Vague descriptions cause misuse as surely as a vague system prompt.
Source: Anthropic, writing-tools-for-agents, 2026-05-31
The three contracts
Every tool has three contracts, and most broken agent systems only design the first one.
| Contract | What it defines | Failure when vague |
|---|---|---|
| Call contract | name, description, schema, validation, auth, idempotency | wrong tool, wrong args, unsafe retries |
| Observation contract | what comes back, how much, what provenance, what follow-up affordances | context flooding, hallucinated interpretation, no audit trail |
| Policy contract | who may call it, when approval is required, what environment it can touch | read tasks mutate state, prod secrets leak into dev work |
This is where Agent Capability Registry and Agent Security Model meet tool design. A tool is not "available" until its policy and observation behavior are also designed.
Tool granularity
| Shape | Use when | Avoid when |
|---|---|---|
| Primitive tool | The action is atomic and safely composable (read_file, grep) |
The agent must perform a 9-step business workflow every time |
| Workflow tool | The domain has a known sequence (create_invoice_and_notify) |
The agent needs exploratory control over each step |
| Search/list tool | The agent needs discovery before action | The result set will be huge unless paginated/summarized |
| Preview/apply pair | Side effects are risky or irreversible | The preview cannot accurately represent the effect |
| Dry-run tool | The world mutation is expensive or external | Dry-run behavior diverges from production behavior |
Good tools have a "smallest useful abstraction" shape. Too primitive and the agent wastes turns assembling workflows. Too high-level and it loses control, debuggability, and recovery.
Output design
Return the smallest next-decision payload:
- status and stable ID,
- short human-readable summary,
- structured fields for downstream calls,
- provenance/source links,
- pagination or continuation token,
- warnings and policy notes,
- suggested safe next actions.
Do not dump raw HTML, entire logs, or 5,000-row tables unless the tool is explicitly a fetch-detail endpoint. Tool output is context; context is scarce.
Registry implication
Public registries such as the MCP Registry can describe install and capability metadata, but they do not make the tool well-designed or trusted. Kevin's stack should treat registry discovery as input to local approval: route through Agent Capability Registry, inspect the tool contract, assign a permission tier, then add the skill/router entry only if the capability is worth making reachable. Source: MCP Registry docs, https://modelcontextprotocol.io/registry/about, 2026-06-19
The build loop
The recommended workflow mirrors Eval-Driven Development: stand up a quick prototype (often wrapped in a local MCP server), generate dozens of realistic evaluation tasks that may each need many tool calls, measure agent success, then collaborate with a coding agent to revise the tools. Anthropic reports that agent-optimized tools measurably outperformed the human-written originals on held-out tasks. Source: Anthropic, writing-tools-for-agents, 2026-05-31
The throughline
The tools most "ergonomic" for agents turn out to be intuitive for humans too. Good tool design is the input side of the same loop where structured outputs govern the output side: constrain and clarify the interface so the stochastic part has the least room to go wrong, and make errors legible to both audiences (Dual-Audience Errors).
Concept Position
| Field | Value |
|---|---|
| Concept family | Brain, memory, and retrieval |
| Concept owned | A tool is a contract between a deterministic system and a non-deterministic agent. Tools written like ordinary APIs underperform; tools des... |
| Category map | Concept System Map |
Timeline
- 2026-07-01 | Concepts category refresh added this page to the Brain, memory, and retrieval family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: A tool is a contract between a deterministic system and a non-deterministic agent. Tools written like ordinary APIs underperform; tools des... Source: User request, 2026-07-01
- 2026-06-19 | Expanded with call/observation/policy contracts, granularity rules, output design, and registry/security implications. Source: whole-wiki concept review, 2026-06-19
- 2026-05-31 | Page created from Anthropic's "Writing effective tools for AI agents." Captured the deterministic-vs-non-deterministic contract framing and the five principles (right tools, namespacing, meaningful context, token efficiency, description as prompt), plus the prototype-then-eval build loop. Source: https://www.anthropic.com/engineering/writing-tools-for-agents, 2026-05-31