Good tools make good agents.
In the agent era, tools are no longer simple wrappers around traditional APIs or function interfaces — they are the decisive factor in whether an agent can complete its work efficiently. To unlock the potential of agents, we need to rethink how tools are built. Traditional software development relies on deterministic logic, but agents are non-deterministic: given identical input, they may produce different outputs. Designing tools for agents therefore demands a new paradigm — and not just how to build tools, but how to make them perform at their maximum. An AI agent is only as strong as the tools we give it. The question is how to make those tools deliver everything they can. Anthropic’s engineering post charts a workable path: anthropic.com/engineering/writing-tools-for-agents.
After reading it, you will be able to: build and test tool prototypes; create and run comprehensive evaluations; and collaborate with agents (like Claude Code) to improve model performance automatically.
What a Tool Is
In computing, a deterministic system produces the same output every time given the same input; a non-deterministic system — an agent — may respond differently under identical starting conditions. Traditional software development builds contracts between deterministic systems: call getWeather("NYC") a thousand times and it returns New York’s weather a thousand identical ways. But a large-model tool is a new kind of software: a contract between a deterministic system and a non-deterministic agent.
Example: a user asks “should I take an umbrella today?” The agent might call the weather tool, might answer from common sense, might first ask a clarifying question (which city, exactly?). Sometimes it will hallucinate; sometimes it will simply fail to understand how to use the tool. Writing software for agents therefore requires rethinking the method from first principles: stop writing tools and MCP servers like ordinary functions or APIs, and design them specifically for agents.
How to Write Tools
First, prototype tools quickly and test them locally. Then run comprehensive evaluations to measure the impact of every change. Repeat the evaluate-and-improve loop with agents until performance on real tasks is strong.
Prototyping. The tutorial uses Claude-based agent building as its example. If you use Claude Code to write tools, give Claude the relevant documentation — the libraries, APIs, or SDKs your tools depend on, including any MCP SDKs. LLM-friendly documentation is usually available as an llms.txt file on official docs sites. Wrap your tool in a local MCP server or a desktop extension (DXT) to connect and test it in Claude Code or Claude Desktop. To connect a local MCP server to Claude Code, run claude mcp add <name> <command> [args...]; for Claude Desktop, use Settings → Developer or Settings → Extensions. You can also pass tools directly into Anthropic API calls for programmatic testing. Then test it yourself to find the weak spots.
Running Evaluations
Generate evaluation tasks. Once the early prototype exists, Claude Code can exercise your tool and generate dozens of prompt-response pairs. The prompts should come from real usage scenarios against real data sources and services — internal knowledge bases, microservices. Avoid oversimplified sandbox environments: they cannot stress the tool under genuinely complex conditions. High-quality evaluation tasks often need many tool calls — sometimes dozens. Good tasks look like: “Schedule a meeting with Jane next week to discuss our latest Acme Corp project. Attach the notes from our last planning meeting and book a conference room.” Or: “Customer ID 9182 reports being charged three times for one purchase. Find all related log entries and determine whether other customers were affected by the same issue.” Weak tasks look like: “Schedule a meeting with [email protected] next week” or “search payment logs for purchase_complete and customer_id=9182.”
Every evaluation prompt should pair with a verifiable response or outcome. Your verifier can be as simple as exact string comparison against ground truth or as advanced as an LLM judging the response — but avoid overly strict verifiers that reject correct answers over formatting, punctuation, or valid alternative phrasing. For each pair you may also specify which tools the agent should call, to measure whether it grasped each tool’s purpose — but since multiple valid paths can solve a task correctly, avoid over-specifying and overfitting the strategy. Run the evals programmatically through direct LLM API calls, using a simple agent loop (a while loop alternating the LLM API with tool calls), one loop per task, each evaluation agent assigned its task prompt and relevant tools. If you evaluate with Claude, enable interleaved thinking so you can see why the agent did or did not call particular tools. Beyond accuracy, collect other metrics: total runtime per tool call and per task, tool-call counts, total token consumption, and tool error rates.
Analyze results. What agents omit from their answers is often more telling than what they include — LLMs do not always articulate their true state. Watch where the agent gets stuck or confused, and use that feedback to locate the tool’s weak points. Review the raw transcripts (tool calls and responses) to catch behavior that never surfaced in the agent’s chain of thought, and remember that your evaluation agent does not necessarily know the correct answer or the best strategy. Analyze your tool-call metrics too: too many redundant calls suggests pagination or token-limit parameters need redesign; too many invalid-parameter errors suggests the tool needs clearer descriptions or better usage examples. And collaborate with the agent: paste the concatenated evaluation transcripts into Claude Code — Claude is excellent at analyzing transcripts and can refactor large batches of tools in one pass.
Principles for Writing Effective Tools
Choose the right tools — more tools does not mean better results. A common pattern: tools that merely wrap existing software features or API endpoints, with no check on whether calling them even suits an agent. The reason agents differ from traditional software is affordances: they perceive and use tools completely differently. An LLM agent’s context is limited — the information it can process at once — while computer memory is cheap and effectively infinite. Consider finding a contact in an address book: traditional software stores and processes contacts one by one, checking each in turn, cheaply. But if an agent’s tool returns every contact and it must read them token by token, it burns its precious context on irrelevant entries. (Imagine finding a contact by flipping the address book page by page — brute-force search.) The better, more natural path — for agents and humans alike — is jumping straight to the relevant page, alphabetically.
So build a small number of thoughtfully designed tools for high-value workflows, aligned with your evaluation tasks, and expand gradually. In the address-book example, implement search_contacts or message_contact rather than a bare list_contacts. Tools can also consolidate — handling multiple discrete operations (or API calls) at the underlying layer beneath a single call: returning results with relevant metadata attached, or completing frequently-chained multi-step tasks in one invocation. Examples: rather than separate list_users, list_events, and create_event tools, build schedule_event, which finds open slots and books directly; rather than read_logs, build search_logs, returning only relevant lines with necessary context; rather than get_customer_by_id plus list_transactions plus list_notes, build get_customer_context, aggregating everything recent and relevant about a customer at once. Every tool should have a clear, distinct purpose — letting the agent decompose and solve tasks the way a human would with the same underlying resources, while reducing the context space that intermediate results would otherwise consume. Too many tools, or tools with overlapping functions, distract the agent and obstruct efficient strategies. Careful, selective planning of what not to build often pays the biggest returns.
Namespace your tools. Agents may connect to dozens of MCP servers and hundreds of tools, including ones other developers wrote. When functions overlap or purposes blur, agents confuse which tool to use. Namespacing — grouping related tools under a common prefix — draws clear boundaries; some MCP clients do this by default. Namespace by service (asana_search, jira_search) or by resource (asana_projects_search, asana_users_search) to help the agent select correctly at the right moment. Prefix versus suffix naming performed differently in tool-use evaluations, so let your evaluation results choose. Skip this and the agent will call the wrong tool, call the right tool with wrong arguments, call too few tools, or mishandle tool responses.
Return meaningful context from tools. Tool implementations should return only high-signal information, prioritizing contextual relevance over flexibility, and avoiding low-level technical identifiers (uuid, 256px_image_url, mime_type). Fields like name, image_url, and file_type are far more likely to drive the agent’s downstream actions. Agents handle natural-language names, terms, and identifiers dramatically better than obscure ones — simply resolving arbitrary alphanumeric UUIDs into semantically meaningful, interpretable language (even a zero-indexed ID scheme) measurably improves Claude’s retrieval accuracy and reduces hallucination. Where the agent needs both — natural language for understanding, technical identifiers for triggering downstream calls (search_user(name='jane') → send_message(id=12345)) — expose a simple response_format enum parameter letting the agent choose “concise” or “detailed” responses. More formats add flexibility, GraphQL-style, letting the agent pick exactly what it receives. In one measured example, a detailed Slack thread response cost 206 tokens while the concise response — thread content only, no thread_ts or channel IDs — cost 72, roughly one-third. Response format itself (XML, JSON, Markdown) also affects evaluation performance: there is no one-size-fits-all answer, because LLMs are trained on next-token prediction and perform best in formats matching their training data — test and choose per task and agent.
Optimize token efficiency in responses. Context quality matters, but so does context quantity. For any tool response that might consume substantial context, combine pagination, range selection, filtering, and/or truncation with sensible default parameter values. Claude Code caps tool responses at 25,000 tokens by default. Agents’ effective context lengths will grow over time — but the need for context-efficient tools will never disappear. If you truncate, give the agent practical guidance: encourage efficient token strategies directly, such as several small targeted searches in a knowledge-retrieval task instead of one broad sweep. And when tool calls produce errors — input validation failures, for instance — design the error responses as prompts themselves, clearly communicating specific, actionable improvements rather than opaque error codes or stack traces.
The Takeaway
The guide’s deepest point is the reframe in its opening: tool design for agents is contract design across a determinism boundary, which makes it a genuinely new discipline rather than API development with new syntax. The practical loop — prototype locally, evaluate programmatically, analyze failures, refactor with the agent’s own help — turns tool quality from a matter of intuition into a matter of measurement. And the principles all point one direction: respect the agent’s context window as the scarcest resource in the system, because every unnecessary token returned by a tool is attention stolen from the task itself. Teams that internalize this — fewer tools, better names, high-signal responses, measurable evaluations — will find their agents improving without touching a single model parameter. That is the quiet revolution of agentic engineering: sometimes the fastest way to a smarter agent is a better tool, not a better model.
