Why is my agent calling the wrong tool and how do I fix it?

Common reasons an agent calls the wrong tool:

1. Tool descriptions are ambiguous or too similar
   If two tools sound alike, the model may pick the wrong one.

   • Fix: make each tool’s name and description very specific and distinct.

2. The prompt doesn’t constrain tool choice
   If the agent isn’t told exactly when to use each tool, it may guess.

   • Fix: add clear routing rules in the system prompt or agent instructions.

3. The tools have overlapping capabilities
   For example, both “search” and “lookup” can seem valid.

   • Fix: split responsibilities more cleanly, or remove redundant tools.

4. The tool schema is underspecified
   Missing/unclear parameters can cause the model to select a fallback tool.

   • Fix: define required arguments precisely, with examples if possible.

5. Few-shot examples are inconsistent
   If your examples show the wrong tool for a task, the model will imitate that.

   • Fix: audit and correct your tool-use examples.

6. Context is too noisy or too long
   Important instructions may get buried.

   • Fix: shorten the prompt, move tool rules earlier, and reduce irrelevant context.

7. The agent is not using a strict router
   A single general-purpose agent may “try” tools instead of selecting deterministically.

   • Fix: add a lightweight intent classifier or router before tool execution.

How to fix it quickly:

• Rename tools to be unambiguous
• Write one-line “use this when…” descriptions
• Add explicit selection rules
• Remove or merge overlapping tools
• Provide 2–5 correct examples
• Log tool calls and inspect failures
• Test with edge cases

A good tool description looks like:

• search_docs: “Use only for finding relevant documents in the knowledge base. Do not use for current weather or calculations.”
• calculate: “Use only for arithmetic or formula evaluation. Never use for searching or retrieval.”

If you want, paste:

• your tool definitions,
• the prompt/instructions,
• and one example of a wrong tool call,

and I can help diagnose the specific cause and rewrite the tool setup.