Tool Design for Agents

This skill distills Anthropic's engineering guidance on writing tools that non-deterministic agents use effectively. Tools are a contract between deterministic systems and non-deterministic agents — an agent may call your tool, ignore it, misuse it, or hallucinate around it. The methodology: prototype fast, evaluate against realistic multi-step tasks, let the agent itself analyze transcripts and rewrite the tools, and optimize every tool for the agent's scarce context rather than for API completeness.

When to use

• Writing or refactoring tool definitions for an agent (MCP server, direct API tools parameter, SDK tool registry).
• Deciding which endpoints of an existing API to expose to an agent, and how.
• Debugging an agent that calls the wrong tool, makes redundant calls, pages through data wastefully, or ignores a tool entirely.
• Reviewing tool names, parameter names, descriptions, or response payloads.
• Building an evaluation for a tool set.

Do NOT use for: designing deterministic function APIs consumed only by code (normal API-design rules apply), or prompt engineering unrelated to tool specs.

Rules

Prototype, then evaluate

1. Stand up a quick local prototype before polishing anything. Give the coding agent documentation for the target libraries/APIs and the MCP SDK; LLM-friendly docs are often published as flat llms.txt files (e.g. https://docs.anthropic.com/llms.txt). Wrap the tools in a local MCP server or Desktop extension (DXT) for hands-on testing: claude mcp add <name> <command> [args...] for Claude Code, or Settings > Developer / Settings > Extensions in the Claude Desktop app. Test the tools yourself first — rough edges you feel are rough edges the agent will hit.
2. Build evaluation tasks from real-world workflows, not toy lookups. Strong tasks require realistic data and multiple — potentially dozens of — tool calls (e.g. "Customer ID 9182 reported that they were charged three times for a single purchase attempt. Find all relevant log entries and determine if any other customers were affected."). Weak tasks hand the agent the answer ("Search the payment logs for purchase_complete and customer_id=9182").
3. Pair every task with a verifiable outcome — exact string comparison or an LLM judge. Do not make verifiers so strict that formatting or punctuation differences fail correct answers. You may note expected tool calls, but avoid overspecifying: multiple valid solution paths usually exist, and overfitting the grader to one strategy hides good behavior.
4. Run evaluations programmatically with a simple agentic loop (a while-loop alternating LLM API calls and tool calls), one task prompt per agent. Ask for reasoning/feedback blocks before tool calls and enable interleaved thinking so you can probe why the agent did or didn't call a tool.
5. Collect more than accuracy: total runtime, tool call count, token consumption, and tool error counts. Redundant calls point at pagination or token-limit tuning; frequent errors point at unclear descriptions or missing input examples.
6. Read the raw transcripts, not just scores — and remember "what agents omit in their feedback and responses can often be more important than what they include" (Anthropic). Example fix from the source: Claude's web search tool kept appending "2025" to queries; improving the tool description corrected it.

Let the agent optimize its own tools

7. Concatenate evaluation transcripts and paste them into Claude Code; ask it to analyze failures and refactor the tools — it can rewrite many tools at once for consistency. Anthropic reports internal Slack and Asana MCP servers measurably beat their human-written baselines this way, with held-out test sets revealing further gains. Most of the source article's advice came from this loop.

Choose and shape the tools

8. Do not wrap every API endpoint 1:1. More tools do not improve outcomes; too many or overlapping tools distract agents from efficient strategies. Build a small set of thoughtful tools targeting the high-impact workflows your eval tasks exercise, each with a clear, distinct purpose.
9. Consolidate multi-step workflows into single tools that do the discrete API calls under the hood. Source examples: schedule_event (finds availability and books) instead of list_users + list_events + create_event; search_logs returning only relevant lines with context instead of read_logs; get_customer_context compiling everything about a customer instead of get_customer_by_id + list_transactions + list_notes.
10. Respect the asymmetry: computer memory is cheap, agent context is not. Prefer targeted retrieval tools (search_contacts, message_contact) over dumps (list_contacts) that force the agent to read everything token-by-token.
11. Namespace tools under common prefixes when many servers/tools coexist — by service (asana_search, jira_search) or by resource (asana_projects_search, asana_users_search). Prefix- vs suffix-based namespacing has non-trivial, LLM-dependent effects on tool-use evals — pick the scheme your own evaluations favor.

Return meaningful, token-efficient context

12. Return only high-signal information. Prefer semantically meaningful fields (name, image_url, file_type) over low-level technical identifiers (uuid, 256px_image_url, mime_type). Resolving UUIDs into natural-language names significantly improves retrieval precision and reduces hallucinations.
13. When downstream calls genuinely need technical IDs (e.g. search_user(name='jane') feeding send_message(id=12345)), expose a response_format enum parameter — DETAILED = "detailed" / CONCISE = "concise" — so the agent chooses. Source measurement on a Slack thread response: detailed 206 tokens (includes thread_ts, channel_id, user_id), concise 72 tokens — roughly one-third the cost.
14. Bound response size: implement pagination, range selection, filtering, and/or truncation with sensible defaults. Claude Code restricts tool responses to 25,000 tokens by default. Effective context will grow, but the need for context-efficient tools will remain.
15. When you truncate, tell the agent what to do next — steer it toward token-efficient strategies such as many small targeted searches instead of one broad search.
16. Make errors actionable: return specific formatting guidance or example inputs, not opaque error codes or raw tracebacks.
17. There is no one-size-fits-all response format (JSON vs XML vs Markdown). LLMs perform better with formats matching their training data — test formats in your evals.

Prompt-engineer the tool spec

18. Treat tool descriptions as one of the highest-leverage surfaces — they load directly into the agent's context. "Think of how you would describe your tool to a new hire on your team" (Anthropic): make implicit knowledge explicit — specialized query formats, niche terminology, how resources relate.
19. Use unambiguous parameter names: user_id, not user. Strict data models plus clear descriptions eliminate ambiguity.
20. Measure description changes with your eval. Anthropic reports Claude Sonnet 3.5 reached state-of-the-art on SWE-bench Verified after precise refinements to tool descriptions dramatically cut error rates.

Checklist

• Prototype wired into a local MCP server / DXT and tested by hand before any polish
• Eval tasks drawn from real workflows; each needs multiple tool calls and has a verifiable outcome
• Verifier tolerant of formatting differences; expected-tool-call specs not overfit to one strategy
• Eval loop records runtime, tool call count, token consumption, and error counts — not just accuracy
• Transcripts read manually; agent-omitted information checked, not just agent-stated feedback
• Transcripts fed to Claude Code with a request to analyze and refactor the tools; re-run on held-out tasks
• Tool set consolidated: workflow tools (schedule_event-style) replace chains of low-level endpoints
• No dump-style tools where a targeted search tool would do
• Tools namespaced with a consistent prefix scheme validated by your own evals
• Responses use natural-language fields; UUIDs resolved to names; response_format (detailed/concise) offered where IDs are sometimes needed
• Pagination/filtering/truncation with sensible defaults; truncation messages tell the agent the next move
• Errors return corrective guidance and example inputs
• Every description written new-hire-clear; parameter names unambiguous (user_id not user)
• Each description change re-measured against the eval before shipping

Anti-patterns

• Wrapping every existing API endpoint as a tool without considering agent affordances.
• Shipping many overlapping tools with fuzzy boundaries — the agent picks wrong or dithers.
• list_* dump tools that flood context and force token-by-token scanning.
• Returning uuid, mime_type, 256px_image_url-style fields when the agent needs names and meanings.
• Opaque error codes and raw tracebacks instead of guidance the agent can act on.
• Eval tasks that are single-call lookups or that embed the answer in the prompt.
• Verifiers that fail correct answers over punctuation, or that hard-require one tool-call sequence.
• Trusting unit-style "it returns data" checks over transcript reading — silent omissions hide there.
• Ambiguous parameter names (user) and descriptions that assume tribal knowledge.
• Hand-tuning tools without an eval, or skipping the agent-driven optimization loop entirely.

Source

• Writing effective tools for agents — with agents — https://www.anthropic.com/engineering/writing-tools-for-agents — 2025-09-11

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.