CONCEPT The description is the tool's user manual — for Claude
Claude never sees your implementation. It sees three fields per tool — name,
description, input_schema — and of these, Anthropic's guidance is blunt: the
description is "by far the most important factor in tool performance." The model decides
whether, when, and how to call a tool almost entirely from its description. A vague
description is the single most common reason Claude picks the wrong tool, hallucinates arguments, or fails to
call a tool it should have.
Write it as documentation for a smart colleague who has never seen the system. The docs say to be extremely detailed and cover four things explicitly:
| Put in the description… | Why Claude needs it |
|---|---|
| What the tool does | Maps the user's intent to this capability |
| When to use it — and when NOT to | Prevents over- and under-triggering |
| What each parameter means & how it affects behavior | Fills arguments correctly instead of guessing |
| Caveats / limitations — what it does not return | Stops Claude expecting data the tool can't give |
CONCEPT Prescriptive triggers beat "what it does"
Newer Opus models reach for tools more conservatively, so a description that only says what the tool does under-triggers. Make the trigger condition explicit: "Call this when the user asks about current prices or recent events." State the negative case too ("Do not use this for historical prices"). The description is not just a definition — it is the routing instruction that decides selection.
DIAGRAM How a description drives selection
the intent + trigger?"} Q -->|"detailed: what / when / params / caveats"| PICK["🟢 Correct tool,
well-formed args"] Q -->|"vague: 'Gets the price.'"| GUESS["🔴 Wrong tool or
guessed / missing args"] GUESS -.->|"rewrite: add when-to-use,
param meaning, caveats"| PICK classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class PICK ok; class GUESS bad;
CODE BAD vs GOOD tool description
Same tool, same schema. Only the prose changes — and that prose is what Claude selects on. This is
Anthropic's own get_stock_price example.
// ❌ BAD — too brief; leaves Claude guessing when to call it and what it returns { "name": "get_stock_price", "description": "Gets the stock price for a ticker.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string" } }, "required": ["ticker"] } } // ✅ GOOD — what it does, when to use it, param meaning, and a caveat { "name": "get_stock_price", "description": "Retrieves the current stock price for a given ticker symbol. " "The ticker must be a valid symbol for a publicly traded company on a " "major US exchange like NYSE or NASDAQ. Returns the latest trade price " "in USD. Use it when the user asks about the current or most recent " "price of a specific stock. It will NOT provide any other information " "about the stock or company.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } }
TRADE-OFFS Rich description vs. terse description
✅ Extremely detailed description
- Correct tool selection, correct arguments
- Fewer wasted turns and retries
- Encodes when-NOT-to-use, so no over-triggering
- Caches with the tools block — the token cost is paid once (2.5)
⚠️ "Gets the price."
- Saves a handful of input tokens
- But: ambiguous selection, guessed args, expects data it can't return
- Every wrong call costs far more than the description would have
EXAM TRAPS
PRACTICE
Q1 · Of name, description, and input_schema, which most determines tool performance, and why?
The description — Anthropic calls it "by far the most important factor." Claude selects and fills a tool almost entirely from its description, since it can't see your implementation. Aim for at least 3–4 sentences covering what it does, when to use/not use it, each parameter's meaning, and caveats.
Q2 · Name four things a good description must include.
(1) What the tool does; (2) when it should be used and when it shouldn't; (3) what each parameter means and how it affects behavior; (4) important caveats/limitations, especially what the tool does not return.
Q3 · Claude keeps skipping a tool you expect it to call. What's the description-level fix?
Add an explicit trigger condition ("Call this when the user asks about X") and, if needed, a stronger system-prompt nudge. Under-triggering is usually a description that says what the tool does but not when to reach for it.