Anthropic "Writing effective tools for agents — with agents" guide

TL;DR

Anthropic published a step‑by‑step guide showing how to create and improve tools for LLM agents via the Model Context Protocol (MCP), using Claude Code to prototype, evaluate, and automatically refine tool implementations. The guide distills five practical principles—tool selection, namespacing, meaningful context returns, token‑efficient responses, and prompt‑engineered specifications—that consistently boost agent performance.

Overview of the guide

The guide explains how developers can collaborate with agents to build high‑quality tools that expand the effective surface area of agentic AI systems. It covers three workflow stages—prototype construction, comprehensive evaluation, and agent‑assisted refinement—followed by a concise set of design principles derived from Anthropic’s internal experiments.

1. Building a prototype

Key actions

  • Stand up a local MCP server or Desktop extension (DXT) and connect it to Claude Code (claude mcp add <name> <command> …) or the Claude Desktop app via the Settings → Developer/Extensions menus.
  • Provide LLM‑friendly documentation (e.g., llms.txt files) for any libraries, APIs, or the MCP SDK the tool depends on.
  • Test manually and gather user feedback to surface rough edges before formal evaluation.

Why it matters

Hands‑on prototyping reveals which tool interfaces agents find ergonomic, allowing developers to iterate before committing to a full evaluation.

2. Running a systematic evaluation

Generating realistic tasks

  • Use Claude Code to produce dozens of prompt‑response pairs grounded in real‑world scenarios (e.g., multi‑step meeting scheduling, log analysis, retention‑offer generation).
  • Avoid overly simplistic prompts; strong tasks should require multiple tool calls and realistic data sources.

Executing the evaluation

  • Implement an agentic loop (while loop) that alternates LLM API calls with tool invocations for each task.
  • Include reasoning and feedback blocks in the system prompt so agents emit chain‑of‑thought (CoT) before tool calls.
  • Enable interleaved thinking in Claude to surface internal reasoning automatically.

Metrics to collect

  • Top‑level accuracy against verifiable ground truth.
  • Runtime, number of tool calls, total token consumption, and error rates.
  • Distribution of tool‑call patterns to identify redundant calls or pagination needs.

Analyzing results with agents

  • Review agents’ CoT and feedback to locate ambiguous descriptions, inefficient implementations, or confusing schemas.
  • Examine raw transcripts (tool calls and responses) for hidden failure modes.
  • Use observed error patterns (e.g., incorrect parameter values) to refine tool specs.

3. Collaborating with agents for refinement

  • Concatenate evaluation transcripts and feed them to Claude Code; Claude can suggest refactorings, resolve inconsistencies, and generate updated tool definitions.
  • Iteratively re‑run the evaluation on the revised tools until performance plateaus on held‑out test sets.
  • Anthropic found that Claude‑generated refinements often surpassed manually written “expert” implementations.

4. Principles for writing effective tools

4.1 Choose the right tools

  • Prioritize high‑impact, task‑specific tools over thin wrappers of existing APIs.
  • Design tools that return only the data an agent needs (e.g., search_contacts instead of list_contacts).
  • Consolidate related operations into a single tool when possible (e.g., schedule_event that both finds availability and creates the event).

4.2 Namespace tools clearly

  • Use consistent prefixes or suffixes (e.g., asana_search, jira_search) to delineate functional domains.
  • Proper namespacing reduces the number of loaded tool descriptions, lowers context load, and minimizes accidental misuse.

4.3 Return meaningful context

  • Emit high‑signal fields (name, image_url, file_type) rather than opaque identifiers (uuid).
  • When technical IDs are required, provide a human‑readable alias or a simple numeric index.
  • Offer a response_format enum (e.g., concise vs. detailed) so agents can request token‑light or richer payloads as needed.

4.4 Optimize token efficiency

  • Implement pagination, range selection, filtering, or truncation with sensible defaults (Claude Code caps tool responses at 25 k tokens).
  • Craft error messages that are actionable rather than cryptic, guiding agents toward corrected inputs.
  • Example: a truncated response saves ~⅔ of tokens compared to a verbose one while still enabling downstream actions.

4.5 Prompt‑engineer tool descriptions

  • Write descriptions as if briefing a new hire: explicit parameter names, clear input/output contracts, and concrete examples.
  • Avoid ambiguous names (user) in favor of precise ones (user_id).
  • Small wording tweaks can yield large performance gains; Claude Sonnet 3.5 achieved state‑of‑the‑art SWE‑bench results after precise description refinements.

5. Looking ahead

Anthropic emphasizes that building tools for agents requires a shift from deterministic software contracts to non‑deterministic, agent‑centric designs. By iterating through prototype → evaluation → agent‑driven refinement, developers can systematically discover what makes a tool “ergonomic” for LLM agents. As the MCP protocol and underlying LLMs evolve, this evaluation‑driven methodology will remain essential for keeping tool ecosystems aligned with increasingly capable agents.

References & resources

Sources