Writing Effective Tools for AI Agents: Anthropic Engineering Guide

Anthropic has introduced a comprehensive methodology for building and optimizing tools for AI agents, shifting the software development paradigm from deterministic contracts (system-to-system) to non-deterministic contracts (agent-to-system). The core takeaway is that tools must be designed specifically for the "affordances" of LLMs—prioritizing context efficiency and semantic clarity over traditional API flexibility.

The Agent-Centric Tooling Paradigm

Traditional software is built on deterministic contracts where a specific input always produces the same output. In contrast, AI agents are non-deterministic; they may choose to call a tool, rely on internal knowledge, or ask for clarification based on the same prompt.

To maximize agent effectiveness, developers must move away from writing tools as standard APIs and instead design them to increase the "surface area" over which an agent can successfully execute strategies. Tools that are ergonomic for agents typically align with intuitive human workflows.

A Systematic Workflow for Tool Development

Anthropic recommends an iterative cycle of prototyping, evaluation, and agent-led optimization to refine tool performance.

1. Prototyping and Local Testing

Developers should start with quick prototypes, utilizing tools like Claude Code to generate initial implementations. To improve one-shot generation, Anthropic suggests providing LLM-friendly documentation (such as llms.txt files) for relevant SDKs or APIs. Tools can be tested locally via:

  • Local MCP Servers: Connected to Claude Code using claude mcp add.
  • Desktop Extensions (DXT): Integrated into the Claude Desktop app.
  • Direct API Calls: Using the Anthropic API for programmatic testing.

2. Evaluation-Driven Optimization

Systematic measurement is required to avoid overfitting and ensure real-world efficacy. This involves:

  • Generating Complex Tasks: Avoiding simple "sandbox" prompts in favor of multi-step, real-world scenarios (e.g., resolving a customer billing dispute by analyzing logs and identifying affected users).
  • Verifiable Outcomes: Pairing prompts with ground-truth responses or using an LLM-based judge for verification.
  • Programmatic Execution: Running evaluation agents in while-loops that alternate between LLM API calls and tool executions.
  • Interleaved Thinking: Utilizing "interleaved thinking" or Chain-of-Thought (CoT) blocks before tool calls to diagnose why an agent failed to use a tool or chose an inefficient path.

3. Agent-Led Refinement

Anthropic found that agents are highly effective at analyzing their own failure transcripts. By feeding evaluation transcripts back into Claude Code, developers can automatically refactor tool implementations and descriptions to ensure self-consistency and performance.

Core Principles for High-Performance Tools

Strategic Tool Selection

More tools do not necessarily equal better performance. Agents have limited context windows compared to the abundant memory of traditional software.

  • Avoid Brute-Force Tools: Instead of a list_contacts tool that returns all data (forcing the agent to read token-by-token), implement a search_contacts tool.
  • Consolidate Functionality: Combine multiple discrete API calls into a single high-level tool. For example, instead of separate list_users and create_event tools, create a schedule_event tool that handles availability and scheduling in one call.

Namespacing and Boundary Definition

To prevent confusion when agents access hundreds of tools across multiple MCP servers, developers should use namespacing (grouping related tools under common prefixes).

  • Example: Using asana_projects_search and jira_projects_search helps the agent delineate boundaries between different services.

Optimizing Context and Signal

Tool responses should prioritize high-signal information and minimize token waste.

  • Semantic Identifiers: Replace cryptic UUIDs with natural language names or 0-indexed IDs to reduce hallucinations.
  • Response Formats: Implement a response_format enum (e.g., CONCISE vs. DETAILED). Concise responses save tokens, while detailed responses provide the IDs necessary for downstream tool calls.
  • Token Efficiency: Use pagination, range selection, and truncation to manage context. Anthropic defaults Claude Code tool responses to 25,000 tokens.

Prompt Engineering for Tool Specs

Tool descriptions act as steering mechanisms within the agent's context. Anthropic notes that precise refinements to tool descriptions were critical for Claude Sonnet 3.5 achieving state-of-the-art performance on the SWE-bench Verified evaluation.

  • Explicit Context: Describe tools as if explaining them to a new hire, including niche terminology and specialized query formats.
  • Unambiguous Naming: Use specific parameter names (e.g., user_id instead of user) to enforce strict data models.

Sources

Related