To debug an AI agent that uses the wrong tool, reconstruct the exact tool list and context the model saw, then test selection without executing anything. Many failures come from overlapping names, descriptions, argument shapes, or missing context, but the trace may instead reveal a correct call with a bad result.
Do not change the prompt until you can name which stage failed.
The current MCP tools specification makes names, descriptions, input schemas, and optional output schemas visible to clients. Those are observable contracts, so inspect them before attributing the failure to hidden model reasoning.
Classify the failure precisely
- Wrong selection: Another visible tool matched the task better.
- Wrong arguments: The chosen tool was correct, but an ID, enum, scope, or required field was wrong.
- Premature call: The agent used the right tool before collecting required context or approval.
- Misleading result: The tool called the backend correctly but returned an ambiguous, stale, or malformed response.
- Unsafe execution: Selection was valid, but authorization, idempotency, or approval failed behind the tool.
These cases need different changes. Renaming a tool does not fix a provider response that says ok before an asynchronous job completes.
Pull the exact trace and tool set
Record the model and version, system prompt, retrieved context, conversation prefix, complete visible tool list, tool definitions, selected name, arguments, result, policy decision, and downstream outcome.
The complete list matters. Reading two suspected files can miss a third tool exposed by a plugin or session. A tool that was unavailable in the failing run cannot explain the choice.
The agent observability guide describes a trace that connects selection to the backend effect.
Put similar tools side by side
[
{
"name": "list_files",
"description": "List entries directly inside one directory.",
"inputSchema": { "directory": "string" }
},
{
"name": "search_files",
"description": "Find files whose path or content matches a query across a directory tree.",
"inputSchema": { "directory": "string", "query": "string" }
}
]
The descriptions state different outputs and triggers. Their schemas reinforce the difference. A generic pair such as “works with files” and “finds files” leaves the model to invent the boundary.
Check shared verbs, nouns, descriptions, examples, required fields, and result shapes. If two tools represent the same user intent with provider-specific implementations, expose one semantic tool and choose the provider behind it when possible.
Make arguments match the task language
Use order_id, customer_id, and deployment_id instead of three unrelated id fields. Add enums, formats, bounds, and descriptions. Derive tenant and user scope from authenticated context rather than asking the model to supply them.
If the tool requires information the agent may not have, state the prerequisite and return a stable missing-context error. Consider a separate read tool that obtains the identifier rather than accepting a guessed free-text value.
The MCP tool design guide covers bounded inputs and structured errors.
Inspect the result before blaming selection
A result should tell the agent what happened and what it may do next. Return stable status, resource or operation ID, and any polling or approval requirement. Do not return a complete provider payload or a generic success string.
For asynchronous work, distinguish accepted, running, completed, and failed. A result that says “created” when creation is pending can cause the agent to call the next tool too early.
Build a selection-only evaluation
Freeze the model, prompt, tool list, and relevant context. Ask for the selected tool and arguments without allowing execution. Include:
- clear positive cases for every tool;
- near-miss cases for the closest pair;
- requests missing required context;
- requests that should call no tool;
- hostile instructions inside retrieved content;
- the original failing request and a sanitized variant.
Repeat nondeterministic cases and report the number of trials. Change one contract element at a time, then rerun the same set. This isolates whether a name, description, schema, or context change improved selection.
Change the smallest failing contract
Rename a vague tool, narrow its description, add a prerequisite, constrain an argument, split a mixed read-write operation, or merge two indistinguishable tools. Reduce the visible set for a task when unrelated tools create collisions.
Use system-prompt guidance for workflow policy that genuinely spans tools. Avoid accumulating one-off rules for every past mistake when the ambiguity lives in the contract.
Re-enable execution only after selection passes
Then test valid, invalid, unauthorized, repeated, interrupted, and policy-gated calls in an isolated environment. A model picking the right tool does not prove that the tool is safe.
The prompt below reconstructs and classifies the failure before recommending changes. It keeps execution off, so the debugger can be run against destructive tools without creating a second incident.