Les descriptions des outils guident la sélection

When Claude decides which tool to call, it does not pick based on the tool's name. It reads each tool's description and reasons about which one fits the task.

This is the single most important fact in tool design: the description is the primary selection mechanism. A tool named process_refund with a vague description is harder to select correctly than a clearly described tool with an awkward name.

If you want reliable behavior, you invest your effort in writing descriptions — not in clever naming.

Names are short and ambiguous. Consider two tools: search_orders and lookup_order. From names alone, which one finds an order by ID? Which one filters a list by date? You cannot tell, and neither can the model.

The description carries the real meaning:

• What the tool is for (purpose).
• What it returns.
• What inputs it expects, with examples.
• Its edge cases and applicability boundaries.

Name the tool sensibly, but never rely on the name to disambiguate behavior.

A strong tool description answers everything the model needs to choose and call it correctly. Include:

• Purpose — the one job this tool does.
• Return values — what comes back, in what shape.
• Input formats with examples — concrete sample arguments.
• Edge cases — empty results, not-found, ambiguity.
• Applicability boundaries — when NOT to use it.

The boundary clause is what stops misrouting between similar tools.

The most common failure is a minimal or ambiguous description. It is a top exam anti-pattern, and the usual wrong answer when a question asks why a tool was mis-selected.

Watch what happens with thin descriptions:

• get_data: "Gets data."
• fetch_info: "Fetches info."

When the task is "find the customer's latest order," the model cannot distinguish these two. It may call the wrong one, or oscillate. Overlapping or ambiguous descriptions cause misrouting — the fix is sharper, non-overlapping wording, not a renamed tool.

When two tools could plausibly apply, each description must explicitly point away from the other. This removes the overlap that confuses selection.

Notice how each description names its sibling and states when to defer to it. That mutual boundary is what keeps the model on the right tool.

Edge cases belong in the description because they shape the model's downstream reasoning, not just the call itself.

Two distinctions matter most:

• An access failure (the system was unreachable — maybe retry) versus a valid empty result (no matches — do not retry, just report).
• What happens on ambiguous input — for example, multiple customer matches.

If the description says "returns empty when no order matches," the model won't treat 'no results' as an error to retry. If it says "returns multiple matches when the name is not unique," the model knows to ask for more identifiers rather than guess.

Even perfect descriptions degrade when there are too many of them. Selection is a reasoning task, and more options dilute it.

• 4-5 tools per agent is the optimal range for reliable selection.
• At 18+ tools, selection reliability degrades noticeably.

So good descriptions and a small toolset work together: scope each agent's tools to its role, then describe those few tools precisely. A bloated toolset cannot be rescued by wording alone.

Description quality and least privilege point the same direction. A research subagent should not carry a refund tool; a read-only reviewer should not carry Write or Bash.

Scoping by role does two things at once:

• Removes overlapping candidates, so the descriptions that remain are easier to tell apart.
• Keeps each agent near the 4-5 tool sweet spot.

Fewer, role-relevant tools means crisper, non-overlapping descriptions — and that is exactly what drives accurate selection.

Descriptions decide which tool fits. The tool_choice parameter is a separate lever that constrains whether and how a tool is called:

• "auto" — the model picks text or a tool (selection still driven by descriptions).
• "any" — the model must call SOME tool; useful to guarantee structured output.
• {"type":"tool","name":"X"} — force one specific tool.

Forcing a tool does not fix a bad description — it just removes the choice. With "auto" or "any", the model is still reading descriptions to choose among candidates, so the wording still has to be clean.

In MCP, not everything should be a tool. The server exposes three primitives, and choosing the right one keeps your tool descriptions focused:

• Tools — actions that DO something (place a refund, run a query).
• Resources — read-only data and context, like schemas or catalogs.
• Prompts — reusable templates.

Modeling a read-only schema or catalog as a Resource rather than a tool removes it from the action-selection pool entirely. That is one fewer ambiguous candidate competing in your descriptions, which directly helps tool selection.

Selection doesn't stop after the first call — the model often has to choose a recovery tool next. That choice depends on the error it gets back.

A generic error like "Operation failed" gives the model nothing to route on. A structured MCP error does:

• isError: true and errorCategory (transient / validation / business / permission).
• isRetryable, a message, the attempted_query, and any partial_results.

With this, the model can intelligently decide: retry a transient fault, fix a validation issue, or escalate a business/permission failure — instead of stalling.

Apply what drives tool selection to a real misrouting bug.

Key takeaways on tool selection:

• Claude selects tools by reading their descriptions, not their names.
• A good description states purpose, return values, input formats with examples, edge cases, and applicability boundaries.
• Overlapping or ambiguous descriptions cause misrouting; draw explicit boundaries that point each tool away from its siblings.
• Document edge cases in the description — especially empty results vs access failures and ambiguous matches.
• Keep 4-5 tools per agent; selection degrades at 18+. Scope tools to the role.
• tool_choice (auto / any / forced) constrains calling but does not replace a clear description.
• Model read-only data as MCP Resources, and return structured errors so the model can route recovery.