D2 · Tool Design & MCP › Cluster 2 · Designing Great Tools

2.1 · Writing Tool Descriptions (the #1 Lever)

The description is what Claude reads

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 doesMaps the user's intent to this capability
When to use it — and when NOT toPrevents over- and under-triggering
What each parameter means & how it affects behaviorFills arguments correctly instead of guessing
Caveats / limitations — what it does not returnStops Claude expecting data the tool can't give
🔑 Anthropic's rule of thumb: aim for at least 3–4 sentences per description, more if the tool is complex. Terseness here is a false economy — a few extra tokens of description save many tokens of wrong tool calls.

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.

Good descriptions are self-contained: Claude should be able to choose correctly from the description alone, without inferring anything from the tool's name or your system prompt.

DIAGRAM How a description drives selection

flowchart TD U["User request"] --> M["Claude reads every tool's description"] M --> Q{"Does a description match
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
There's a ceiling: don't pad with irrelevant prose. Detail must be load-bearing (behavior, triggers, caveats) — filler dilutes signal and burns context on every request.

EXAM TRAPS

Trap: "Better model = shorter descriptions are fine." → No. The description is the #1 performance lever regardless of model. Anthropic's guidance to write extremely detailed descriptions is model-independent.
Trap: Describing only what the tool does. → Omit "when to use / when NOT to use" and Claude over- or under-triggers. Make the trigger condition explicit in the description.
Trap: Relying on the tool name to convey behavior. → The name is a short identifier; the description carries meaning. A great name with a one-line description still selects poorly.
Trap: Forgetting caveats. → If you don't state what the tool does not return, Claude may call it expecting data it can't provide, then fail downstream.

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.