Effective Tool Descriptions

Tool descriptions are the primary mechanism Claude uses to select between tools. A vague description guarantees unreliable selection. This lesson covers how to write descriptions that make tool selection deterministic, when to split overlapping tools, and how to avoid system-prompt-induced misrouting.

What a Good Description Contains

• Purpose. One sentence. What does this tool do?
• Input format. What parameters does it expect? What types? What format constraints?
• Example queries. 1-2 concrete examples of valid input.
• Edge cases. What does it do when the input is empty, malformed, or out of bounds?
• When to use vs alternatives. If there's a similar tool, what distinguishes them?

Symptom: Tools Misrouting

If your agent has two similar tools — say, analyze_content and extract_web_results — and Claude is calling the wrong one frequently, the most effective first step is expanding the descriptions to differentiate them. Few-shot examples in the system prompt are a worse fix because they don't address the underlying ambiguity.

Before

{
  "name": "analyze_content",
  "description": "Analyzes content"
}

After

{
  "name": "analyze_content",
  "description": "Extracts structured data from text passages provided directly. Use for content the user pastes into the conversation. Do NOT use for content fetched from URLs — use extract_web_results for that."
}

Splitting Generic Tools

A tool called analyze_document that supposedly handles extraction, summarization, and verification is overloaded. The model has no way to predict which behavior it will get on any given call. Split it into purpose-specific tools:

• extract_data_points — pulls specified fields from a document
• summarize_content — produces a TL;DR
• verify_claim_against_source — checks whether a claim is supported by a document

Each has a clear contract. The model picks the right one based on intent.

Naming Eliminates Overlap

Tool names matter. analyze_content and analyze_text sound the same to the model. Renaming one to extract_web_results eliminates the overlap by encoding the distinguishing factor in the name itself.

System Prompt Wording Can Bias Tool Selection

If the system prompt says "You are a research assistant who searches the web for information," Claude is biased toward web-search tools — even when the user's question could be answered from a different tool. Write system prompts that describe capability, not preferred tools.

Skills to Develop

1. Write tool descriptions that include purpose, inputs, examples, edge cases, and when-to-use-vs-alternatives.
2. Recognize when overloaded tools should be split into purpose-specific alternatives.
3. Audit system prompts for wording that biases tool selection unintentionally.