Your Tool Descriptions Are the #1 Lever for Agent Performance — Here's How to Write Them

TL;DR: Rewriting a tool description (no code changes) is the single highest-leverage optimization in agent development — Anthropic's engineering team has moved benchmarks to state-of-the-art with description tweaks alone.

Anthropic's engineering team published Writing effective tools for AI agents, distilling what they've learned building Claude Code and internal agents. The core insight: Claude reads your tool descriptions the way it reads a system prompt — those strings dominate how the model behaves.

The five moves that matter

1. Write descriptions like thorough documentation, not labels

Bad: "description": "Gets the stock price."

Good: "description": "Retrieves the current market price for a US-listed stock by ticker symbol (NYSE or NASDAQ). Returns the latest trade price in USD. Use this when the user asks about the current price of a specific public company. Does not return historical data or analyst estimates."

Aim for 3–4 sentences: what it does, when to use it, what it returns, what it doesn't cover. The description is loaded into the model's context on every call — it's your most direct lever.

2. Consolidate related operations into one tool

Three thin wrappers (list_users, get_user, update_user) force Claude to select among them, increasing ambiguity and context overhead. A single user_manager tool with an action enum cuts selection errors and simplifies your API surface.

3. Namespace by service or resource

When your tool surface grows, prefix by domain: github_list_prs, slack_send_message, asana_projects_search. Distinct prefixes reduce hallucinated calls and help Claude route correctly when hundreds of tools are in scope.

4. Return semantic information, not raw IDs

Returning a UUID makes Claude guess what it refers to. Returning "Austin, TX — 32°C, sunny" lets it reason directly. Keep tool responses under 25,000 tokens; if you must truncate, tell Claude what was dropped and how to narrow the query.

5. Use Claude to improve Claude's tools

Ask Claude Opus to review your tool definitions and suggest improvements:

"You're an agent developer. Review these tool definitions and suggest more precise descriptions, any schema improvements, and where to consolidate."

This prototype → evaluate → collaborate loop is how Anthropic's own teams iterate. The model that will call your tools is also the best reviewer of those tools.

Quick checklist

• Every tool has a ≥3-sentence description with when-to-use guidance
• Related operations consolidated into one tool with an action parameter
• Tool names prefixed by service/resource when you have more than 5 tools
• Responses return readable identifiers, not opaque IDs
• Response size is bounded (pagination, filtering, or truncation defaults)
• You've asked Claude Opus to review and improve your definitions

Sources: Writing effective tools for AI agents — Anthropic Engineering | Define tools — Claude Platform Docs