[Blog](https://cohesivity.ai/blog)

Reliability & production

Published Jul 30, 2026·Updated Aug 30, 2026

![](https://cohesivity.ai/authors/anshu.webp)![](https://cohesivity.ai/authors/arag.webp)[Anshu](https://www.linkedin.com/in/aanshuaggrawal120/) and [Arag](https://www.linkedin.com/in/aragagrawal/)

# How to Debug an AI Agent That Uses the Wrong Tool

[Read as Markdown](https://cohesivity.ai/blog/how-to-debug-an-ai-agent-that-uses-the-wrong-tool.md)

Bad call

Inspect

Select

Right tool

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](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) 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

1. **Wrong selection:** Another visible tool matched the task better.
2. **Wrong arguments:** The chosen tool was correct, but an ID, enum, scope, or required field was wrong.
3. **Premature call:** The agent used the right tool before collecting required context or approval.
4. **Misleading result:** The tool called the backend correctly but returned an ambiguous, stale, or malformed response.
5. **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](https://cohesivity.ai/blog/ai-agent-observability-what-to-monitor) describes a trace that connects selection to the backend effect.

## Put similar tools side by side

```json
[
  {
    "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](https://cohesivity.ai/blog/how-to-design-mcp-tools-agents-can-use-reliably) 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.

or send it to[Claude Code](https://claude.ai/new?q=Inspect+this+repository%27s+complete+tool+definitions+and+any+trace+for+the+reported+wrong-tool+run.+Do+not+invoke+tools+or+edit+code.+Reconstruct+the+exact+visible+tool+list%2C+descriptions%2C+schemas%2C+context%2C+model%2C+and+prompt+version.+Classify+the+failure+as+wrong+selection%2C+right+tool+with+wrong+arguments%2C+premature+call%2C+or+correct+call+with+misleading+result.+Build+selection-only+cases+for+the+failing+request%2C+near+misses%2C+missing-context+requests%2C+and+requests+that+should+use+no+tool.+Show+the+closest+tool+collisions+and+propose+the+smallest+name%2C+description%2C+schema%2C+or+context+change+before+changing+the+system+prompt. "Send to Claude")[Cursor](https://cursor.com/link/prompt?text=Inspect+this+repository%27s+complete+tool+definitions+and+any+trace+for+the+reported+wrong-tool+run.+Do+not+invoke+tools+or+edit+code.+Reconstruct+the+exact+visible+tool+list%2C+descriptions%2C+schemas%2C+context%2C+model%2C+and+prompt+version.+Classify+the+failure+as+wrong+selection%2C+right+tool+with+wrong+arguments%2C+premature+call%2C+or+correct+call+with+misleading+result.+Build+selection-only+cases+for+the+failing+request%2C+near+misses%2C+missing-context+requests%2C+and+requests+that+should+use+no+tool.+Show+the+closest+tool+collisions+and+propose+the+smallest+name%2C+description%2C+schema%2C+or+context+change+before+changing+the+system+prompt. "Send to Cursor")[Codex](https://chatgpt.com/codex?prompt=Inspect+this+repository%27s+complete+tool+definitions+and+any+trace+for+the+reported+wrong-tool+run.+Do+not+invoke+tools+or+edit+code.+Reconstruct+the+exact+visible+tool+list%2C+descriptions%2C+schemas%2C+context%2C+model%2C+and+prompt+version.+Classify+the+failure+as+wrong+selection%2C+right+tool+with+wrong+arguments%2C+premature+call%2C+or+correct+call+with+misleading+result.+Build+selection-only+cases+for+the+failing+request%2C+near+misses%2C+missing-context+requests%2C+and+requests+that+should+use+no+tool.+Show+the+closest+tool+collisions+and+propose+the+smallest+name%2C+description%2C+schema%2C+or+context+change+before+changing+the+system+prompt. "Send to Codex")[opencode](https://opencode.ai/?q=Inspect+this+repository%27s+complete+tool+definitions+and+any+trace+for+the+reported+wrong-tool+run.+Do+not+invoke+tools+or+edit+code.+Reconstruct+the+exact+visible+tool+list%2C+descriptions%2C+schemas%2C+context%2C+model%2C+and+prompt+version.+Classify+the+failure+as+wrong+selection%2C+right+tool+with+wrong+arguments%2C+premature+call%2C+or+correct+call+with+misleading+result.+Build+selection-only+cases+for+the+failing+request%2C+near+misses%2C+missing-context+requests%2C+and+requests+that+should+use+no+tool.+Show+the+closest+tool+collisions+and+propose+the+smallest+name%2C+description%2C+schema%2C+or+context+change+before+changing+the+system+prompt. "Send to OpenCode")