Descriptions Route Tool Calls

Overview of Tool Descriptions

Learn how Claude relies on tool descriptions as the primary selection signal and how to write precise descriptions to prevent misrouting in production.

Descriptions are Selection Signals

Claude chooses a tool by reasoning over its description rather than its name. If two descriptions overlap, the model cannot distinguish between them.

Consider a query like check my order #12345. If both tools use the word Retrieves, the model might guess the wrong one.

Renaming a tool is not enough. The description is the primary evidence Claude uses to decide which tool to call.

The Danger of Ambiguity

Vague descriptions lead to misrouting. For example, get_customer and lookup_order both sound similar if they only say Retrieves information.

In these cases, the first plausible match often wins. This happens even if your tool names are clear and distinct.

Anthropic recommends providing at least 3 to 4 sentences per tool. Detailed descriptions are the most important factor in tool performance.

The Lowest Effort Fix

When tools are misrouted, your first intervention should be expanding the descriptions. This is the most cost-effective solution.

Adding few-shot examples creates token overhead. Building a routing classifier is often over-engineered for simple selection problems.

Rewriting two strings removes the root cause. It uses the language understanding you have already paid for without adding new infrastructure.

How to Repair Descriptions

To fix lookup_order, specify that it requires an order number in the #NNNNN format. State exactly what data the tool returns.

Explicitly tell the model to send identity questions to get_customer instead. This creates a clear boundary between tools.

Better descriptions should always come before complex fixes like tool consolidation or custom routing logic.

Putting It All Together

When Claude decides which tool to call for a user prompt, it relies primarily on the _____.

• tool description
• tool name

Answer: tool description

Claude chooses tools by reasoning over their descriptions rather than their names. Renaming a tool does not resolve selection ambiguity if descriptions overlap.

To repair overlapping tool descriptions, specify the exact parameter _____ for inputs and define explicit operational _____ to route specific queries correctly.

Answer: To repair overlapping tool descriptions, specify the exact parameter format for inputs and define explicit operational boundaries to route specific queries correctly.

Clarifying parameter formats (such as requiring #NNNNN) and setting explicit boundaries (telling Claude which tool handles identity questions) removes ambiguity between tools.

An agent misroutes user queries between two tools that have vague, overlapping descriptions. What is the most cost-effective first intervention?

• Expand and differentiate the descriptions of both tools
• Add several few-shot examples to the system prompt
• Build a custom routing classifier to pre-evaluate queries
• Consolidate both tools into a single unified tool

Answer: Expand and differentiate the descriptions of both tools

Expanding and differentiating descriptions removes the root cause of misrouting without added token overhead, custom classifiers, or structural tool changes.