Tool Descriptions Are the Selection Mechanism

When you pass tools to the Messages API, Claude does not see your source code — it sees only each tool's name, description, and input_schema. These three fields are injected into a constructed system prompt. The description is how Claude decides whether and when to call a tool. A weak description is the single most common cause of a model picking the wrong tool, hallucinating arguments, or skipping a tool it should have used.

What a good description contains

Anthropic's own guidance is blunt: "Provide extremely detailed descriptions. This is by far the most important factor in tool performance." Aim for 3–4 sentences minimum, covering:

What the tool does
When it should be used — and when it should not
What each parameter means and how it affects behavior
Caveats and limitations (e.g. what it does not return)

json

The parameter-level description fields matter too: they tell Claude the expected format ("e.g. AAPL"), so it produces well-formed inputs.

Avoiding overlap and ambiguity

As your tool surface grows, the failure mode shifts from "bad description" to "two tools look interchangeable." Mitigations:

Consolidate related operations. Instead of create_pr, review_pr, merge_pr, expose one github_pr tool with an action enum. Fewer, more capable tools reduce selection ambiguity.
Use meaningful namespacing. Prefix names by service: github_list_prs, slack_send_message. This makes selection unambiguous as the library grows and is especially important with the Tool Search tool.
Make boundaries explicit in prose. If search_orders and search_products could be confused, each description should state what it does not cover ("This searches orders only, not the product catalog").

Renaming vs. duplicating

If a tool's purpose drifts, rename and rewrite the description rather than adding a near-duplicate. Two tools whose descriptions overlap force Claude to guess, and the guess is non-deterministic. Treat the description as the public API contract: it changes when behavior changes.

input_examples for complex schemas

For tools with nested objects or format-sensitive inputs, add an optional input_examples array. Each example must validate against input_schema (invalid examples return a 400). Examples are cheaper to reason about than long prose for showing which optional fields to include and how to format them, but descriptions still come first.

Exam focus