Tool design (agent–computer interface)
Designing an agent's tools — names, descriptions, parameters, outputs, errors — so the model picks and uses them correctly and cheaply.
An AI agent is only as good as its tools. Tool design is making each tool easy for a model to understand and use: a clear name, a description that says when to use it, simple inputs, and short, useful results.
A handy test: if a new colleague couldn't tell from the description when to use the tool, the model probably can't either.
Labelling the switches in a shared office: "Lights — meeting room B" gets used correctly; "Switch 3" gets flipped at random.
One tool per existing API endpoint. Dozens of overlapping low-level tools inflate context, confuse selection, and force the agent to stitch many calls together.
Tool definitions are prompt text for Tool use & function calling. Anthropic's Sept 2025 guidance, and practice since, converge on: build tools around agent tasks, not API endpoints (schedule_meeting rather than list_users + list_events + create_event); keep the set small and non-overlapping, and namespace related tools (crm_search_contacts, crm_update_deal) because overlapping tools cause selection errors and every definition costs tokens; use unambiguous parameter names, enums and examples, and validate strictly; return high-signal, human-readable fields (names, not opaque UUIDs) with a response_format option for concise vs detailed; paginate, filter and truncate with a hint (Claude Code caps tool responses at 25,000 tokens by default); and make errors actionable ("date must be YYYY-MM-DD; got 15/10") so the The agent loop (ReAct) can self-correct.
Design for safety too: separate read and write tools, scope credentials per tool (Least privilege), make writes idempotent (Idempotency), and mark destructive tools for Human in the loop approval. Evaluate empirically: run realistic tasks, read the transcripts, and measure selection accuracy, calls per task and tokens per call.
5–15 task-shaped tools per agent, namespaced by system; descriptions that say when to use and when not to; enums for closed sets; identity from the session, not arguments; outputs ≤ 2–5k tokens with pagination and a truncation hint; response_format concise|detailed; errors with a fix suggestion; reads and writes split; writes idempotent; tool evals in CI.
Developer-tools agent: get_logs() returned 50,000 lines and blew the context. Redesigned as search_logs(service, level="ERROR", since="1h", limit=50, response_format="concise") returning timestamp, message and trace id, plus "48 more — narrow with since= or query=". Tokens per call fell from ≈ 40k to ≈ 1.5k; tool calls per incident from 9 to 4; tool-selection errors (picking get_metrics for log questions) from 12% to 2% after rewriting both descriptions to say when not to use them.
Recommend consolidating endpoint-shaped tools into a few task-shaped ones, then show how you'd measure: selection accuracy, calls per task, tokens per call, from transcripts. "Design tools for the agent's task, not your API's shape."
Expect: "you have 80 tools from MCP servers" — load per workflow, namespace, and let the agent search tools instead of preloading all definitions.
Endpoint-shaped
- list_users, list_events, create_event
- Returns raw UUIDs
- Dumps full payloads
- Error: 400 Bad Request
Task-shaped
- schedule_meeting(attendees, window)
- Returns readable names
- Filtered, paginated, concise
- Error says how to fix the input
Numbers worth knowing
- Tool response cap in Claude Code
- 25,000 tokens defaultAnthropic, Sept 2025
- Target tool-selection error
- < 3% of callsmeasured on transcript review
- Tools per agent before selection degrades
- ~15–20rule of thumb; measure on your own eval
How to decide
| When | Do this |
|---|---|
| The agent chains 3+ calls to do one common job | Add a task-level tool that does the job in one call. |
| Two tools are often confused | Merge them or rewrite both descriptions with "use X when…, not when…". |
| A tool returns > 5k tokens | Add filters, pagination and a concise response format. |
Cost maths
Tool cost = definitions on every call + results. 40 endpoint tools × 300 tokens = 12k definition tokens per call; 12 task tools × 350 = 4.2k. At 10 calls/run, 100k runs/month, $3 / M input (illustrative, Oct 2026): $36k vs $12.6k a month for definitions, before counting the smaller results and fewer calls the task-shaped tools also produce.
Operating it
- Tool-selection errors > 5% of calls
- Median tool result > 5k tokens
- Agents need > 20 tools in one context (split by workflow or add tool search)
- Tool-selection error rate from sampled transcripts (alert > 5%)
- Tokens per tool result p95 (alert > 5k)
- Calls per task (alert +30% vs baseline)
- Validation errors per tool (alert > 3%)
When it goes wrong
An e-commerce catalog agent kept updating the wrong product variant's price.
Merchant complaints; traces showed update_price(id) called with a parent product id.
search_products returned opaque UUIDs for parents and variants without labels; the description of update_price didn't say it needed a variant id.
Search returns {variant_id, sku, title, size, colour}; update_price takes sku (readable, validated) and errors with "this is a parent product; choose a variant: …"; wrong-variant updates fell to 0.
Related terms
Where it shows up
Sources
- Writing effective tools for agents — with agents — Anthropic, 2025blog
- Tool use with Claude — Anthropic, 2026docs
- Building effective agents — Anthropic (Schluntz & Zhang), 2024blog
Check yourself
Three questions. Every option is explained once you answer.