Repair tool ambiguity before adding routing

Learning objective

Diagnose misrouting among overlapping tools; rename and clarify responsibility boundaries before adding complex routing infrastructure.

Core idea

When Claude repeatedly chooses the wrong tool, first ask whether the exposed interface makes the right choice identifiable. Two tools named analyze_content and analyze_document, both described as analyzing information, require the model to infer distinctions that the architect has not supplied.

The CCAR-F exam guide uses that pair to illustrate misrouting and suggests renaming analyze_content to extract_web_results with a web-specific description. These are design examples, not built-in Anthropic tools. The important change is the responsibility made visible by the name and description.

Repair the interface before building a classifier, router, or another agent around it. Anthropic recommends distinct tool purposes, meaningful namespacing, and evaluation of actual calls. Additional infrastructure earns its place when the task needs explicit control; it does not explain an ambiguous tool on the model’s behalf. See 1.1.3 for model-driven selection versus fixed routing.

How it works

Identify what failed in the transcript

For Messages API client tools, Claude returns tool_use blocks identifying the requested tool and input. Your application executes the operation and returns a matching tool_result. Inspect those blocks alongside the request and exposed definitions. See 1.1.2 for history correlation.

Separate three failures. A wrong operation is a selection failure. The right operation with an unsuitable identifier or query format is an argument failure. The right operation with valid arguments but an irrelevant or incomplete result is a result-contract or implementation failure. They can occur together, but require different repairs.

For example, an assistant asked to extract facts from web-search results calls a document-summary operation. If the chosen operation only produces a narrative overview, valid arguments do not repair the mismatch. Conversely, a call to extract_web_results using a document identifier instead of a search-result identifier points to input semantics, even when the name is correct.

Anthropic’s tool-engineering guidance recommends reading raw transcripts rather than relying only on an agent’s explanation of its behavior. The explanation might omit a mistaken call. Treat the requested operation and returned evidence as the observable facts for diagnosis.

Make each responsibility distinguishable

Compare the overlapping definitions side by side. Ask which source each operation accepts, which outcome it produces, and which adjacent outcome it excludes. If you cannot assign representative requests confidently, the ambiguity exists before model inference.

For the exam guide’s example, rename analyze_content to extract_web_results only if its implementation extracts information from web results. Explain the accepted web-result identifiers, the extracted evidence returned, and why an uploaded document belongs to the document tool. The name is a summary of the contract, not a replacement for it.

Then clarify analyze_document. If it actually summarizes an ingested document, expose that purpose through a name such as summarize_document and a description of the narrative result. If it performs several unrelated operations, the appropriate repair might require splitting responsibilities; see 2.1.3. Do not fabricate a narrow description for behavior that remains generic.

A useful boundary is symmetric. The web tool points document-summary requests to summarize_document; the document tool points search-result extraction to extract_web_results. Both descriptions explain supported inputs and outputs.

Rename the exposed contract and its references

For user-defined API tools, tools[].name is the identifier the model receives. The application must execute calls under the exposed identifier. A rename therefore needs the tool definition, the dispatch mapping, and any supplied instructions or examples to agree.

Changing a function’s internal name while leaving tools[].name unchanged does not improve the model’s interface. Changing only the exposed name while leaving a dispatcher expecting the previous name breaks execution.

Use service or resource namespacing when tools from different systems have similar verbs. Anthropic gives examples such as asana_search and jira_search, with further resource distinctions where needed. A shared prefix groups tools; the rest of the name must still identify a meaningful operation. Renaming both ambiguous tools to variants of research_analyze preserves the original problem.

Anthropic reports that prefix-versus-suffix choices can affect evaluations and that effects vary by model. Evaluate a naming scheme against your workload rather than assuming one lexical order guarantees correct selection.

Evaluate the repair before adding complexity

Build representative requests that require the web tool, requests that require the document tool, and requests that need both. Include different wording for the same intent and cases with insufficient input. Pair each task with a verifiable outcome, following Anthropic’s evaluation guidance.

Observe actual tool calls and results. A correct name with evidence from the wrong source still fails. A compound task might have several valid execution paths; score the required evidence and outcomes rather than demanding one incidental order.

Compare the repair against the same evaluation tasks. Record wrong-tool calls, invalid arguments, tool errors, total calls, and task completion. Anthropic recommends call counts, errors, runtime, and token use alongside accuracy. Those observations reveal whether clearer contracts improve selection or merely cause extra calls until something works.

If ambiguity persists, inspect the supplied system prompt for a competing keyword rule; see 2.1.4. If the task requires deterministic routing, implement that explicitly as the control strategy described in 1.1.3. The decision should follow the actual requirement, not an assumption that descriptions cannot be improved.

Key distinctions and trade-offs

Misrouting versus invalid input: A call to the wrong tool needs a responsibility repair. A call to the right tool with an invalid argument needs clearer parameter meaning or examples.

Description repair versus examples: Few-shot routing examples in the system prompt are not the first fix. They show which tool earlier requests mapped to, while both descriptions still claim the same job, so a request worded differently from the examples can misroute again. Anthropic calls detailed descriptions by far the most important factor in tool performance; repair them first. input_examples is a different mechanism: schema-validated argument objects that show how to fill complex, nested, or format-sensitive arguments, so they serve argument failures rather than selection; see 2.1.1 for where the field is supported.

Rename versus redesign: A rename exposes an existing distinction. A redesign changes what an operation does. Align the name with implemented behavior before testing either.

Routing versus interface clarity: A router chooses an operation under application control. A description supplies information for model selection. Use each for its own purpose; a router has its own maintenance and correctness obligations.

Match the repair to the pattern the transcript shows:

Architecture / decision scenario

A multi-agent research system exposes analyze_content and analyze_document. Both descriptions say “Analyze supplied information.” Requests about retrieved web evidence frequently invoke the document operation, which returns a summary without web-result attribution.

The architect inspects tool_use blocks and confirms a selection failure: the inputs are valid for the chosen tool, but its output cannot satisfy the request. They rename the web operation to extract_web_results, define its accepted search-result identifiers and evidence output, and rename the narrative document operation to summarize_document. Each description states the other’s selection condition.

They update the dispatcher and prompt examples to use the exposed names. Evaluation requests include extracting a reported figure from web results, summarizing an uploaded report, and comparing both sources. The checks require the relevant evidence, so a plausible narrative with missing web attribution cannot count as success.

If the repaired interface still misroutes only when a system prompt says “Use the document analyzer for all analysis,” that instruction becomes the next diagnosis. The team removes the competing association before proposing a routing service. A separately identified need for deterministic source restrictions would justify application-controlled routing on its own terms.

Common exam traps

• Adding a routing agent before inspecting overlapping descriptions.
• Adding few-shot routing examples to the system prompt before repairing the descriptions that overlap.
• Renaming a tool without clarifying its accepted source and returned outcome.
• Merging two tools that read different sources into one tool as the first fix for their overlap.
• Adding a stronger “always use” rule to the system prompt, which creates a new keyword association.
• Calling schema-valid arguments proof that the correct operation was selected.
• Updating the exposed name without updating application dispatch and prompt references.
• Measuring only the final prose while ignoring wrong calls and missing evidence.
• Assuming a namespace or naming convention guarantees correct selection without evaluation.

What to remember

Diagnose selection, arguments, and results separately. Repair the exposed name and description around a distinct implemented responsibility, update every reference, and evaluate actual calls. Add explicit routing when control requirements demand it.

Knowledge check

References

• Anthropic, Define tools
• Anthropic, Tool use with Claude
• Anthropic, Writing effective tools for agents
• Anthropic, Claude Certified Architect – Foundations Exam Guide