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)

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.

Too many tools degrades selection

Descriptions only work if the model can compare them. The exam's developer-productivity scenario gives an agent 18 tools instead of 4–5 and shows the result: wrong-tool calls, hesitation, and long turns spent reasoning about which of three overlapping "fetch" tools to use. Selection accuracy falls as the tool list grows, because every description competes for the same attention. Three fixes, in order of proportionality:

1. Cut the list per role. A code-review agent needs Read, Grep, Glob and one review-output tool — not the deployment, ticketing and email tools another role uses. Scope per AgentDefinition.
2. Scope shared cross-role tools narrowly. If a verify_fact tool must be available to both the researcher and the writer, give it one tight description and one job; do not clone it as check_fact, validate_claim, fact_lookup.
3. Replace generic with constrained. A generic fetch_url(url) invites the model to browse anywhere and return unbounded HTML. A constrained load_document(doc_id) that resolves only against your indexed corpus is easier to select, safer, and returns clean text. Constrained tools with precise descriptions beat powerful generic ones.

When a scenario shows misrouting with a long tool list, the most effective first step is to reduce and scope the tools — not to add a router agent, force tool_choice, or fine-tune. (Exam Guide v1.0 task statement 2.3;(CCAR-F Exam Guide v1.0, Jul 2026)

Exam focus

Remember the hierarchy: description is the selection mechanism, and "extremely detailed descriptions" is the #1 lever for tool-use accuracy. Know the three model-visible fields (name, description, input_schema). When a scenario shows the model choosing the wrong tool, the answer is almost always "improve/disambiguate the descriptions" or "consolidate overlapping tools" — not "fine-tune" or "add more tools."