---
title: Why AI Agents Call the Wrong Tool: 7 Causes From Real Runs
description: Codex never found the tools in 8 of 80 runs; Claude picked tools from names alone. 7 causes of wrong tool calls from real agent runs, with counts and fixes.
canonical: https://spiritroom.app/blog/why-agents-call-the-wrong-tool/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/why-agents-call-the-wrong-tool/ for agents. Index: /llms.txt

[Blog](/blog/) / [How to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/)

# Why AI agents call the wrong tool: 7 causes we saw in recorded runs

When an agent calls the wrong tool, the usual advice is to write better descriptions. Sometimes that's it. But in recorded runs on a 99-tool production server, most wrong or missed calls had other causes: the agent never found the server, chose from names alone, used the word the user saw in the app, or left for the browser. Here are the seven causes, with counts.

Leonid Bugaev · Published 21 Oct 2026

**TL;DR**

- **1. Never found the tools:** Codex didn't reach the server in 8 of 80 live runs (5–19%) and tried a browser instead.
- **2. Chose from names alone:** Claude Code's model saw only tool names and picked which definitions to load from those.
- **3. Went for the closest-looking tool:** with no hint, Claude skipped a start-here tool in 23 of 24 mock runs.
- **4. The user's word, not the API's:** a label from the app's screen sent answers wrong, and one job passed in only 4 of 10 Claude Code runs.
- **5. Heavy overview tools:** 4 of 5 Codex status runs read a 14,517-token overview to get a few numbers.
- **6. Truncated results, re-called:** in 5 of 5 runs of one job, Codex called the same feed twice after the first result was cut.
- **7. Left for the browser:** 13 of 36 early runs drove a signed-in browser instead of MCP.
[The seven causes at a glance](#summary)[1. Never found the tools](#never-found)[2. Chose from names alone](#names)[3. The closest-looking tool](#closest)[4. The user's word, not the API's](#vocabulary)[5. Heavy overview tools](#heavy)[6. Truncated, then re-called](#truncated)[7. Left for the browser](#browser)[How we measured](#how-we-measured)[FAQ](#faq)

## The seven causes at a glance

We recorded Claude Code and Codex runs on a 99-tool production MCP server: live read-only jobs and controlled mock experiments. Every wrong or missed tool call we found fits one of seven causes.

Causes of wrong or missed tool calls, recorded runs, 16–18 Oct 2026

| Cause | Seen in | Fix |
| --- | --- | --- |
| 1. Never found the tools | Codex, 8 of 80 live runs | User vocabulary in names and first lines |
| 2. Chose from names alone | Claude Code default (tool search on) | Names that say what the tool is for |
| 3. Went for the closest-looking tool | Claude 23 of 24, Codex 15 of 24 mock runs without a hint | A start-here tool and a hint |
| 4. The user's word, not the API's | Claude Code, one job 4 of 10 passes | Map app labels to API values |
| 5. Heavy overview tools | Codex, 4 of 5 status runs | A small summary by default |
| 6. Truncated, then re-called | Codex, 5 of 5 runs of one job | Smaller results, a summary line |
| 7. Left for the browser | Codex, 13 of 36 early runs | Block it in tests; make MCP the obvious path |

## 1. The agent never found the tools

Codex 0.161 doesn't show the model your tools up front. The model searches tool metadata from code, and the search can come back empty. Across two live rounds of 8 everyday questions × 5 runs, Codex never reached the server's tools in **8 of 80 runs (5–19%)**: it said no connector was available and tried to open a browser. The server had listed all 99 tools every time. When Codex did find them in the first round, it answered correctly in 34 of 34.

Search matches words, so the fix is vocabulary: the words users say (“plan”, “credits”, “performing best”) in tool names and the first line of descriptions. Our runs can't separate how much was the tool wording and how much the app's search, but wording is the part you control. More in [how many MCP tools is too many](/blog/how-many-mcp-tools-is-too-many/).

## 2. The model chose from names alone

With tool search on (the default), Claude Code 2.1.301 showed the model a reminder listing **names only**: 99 server tools plus 14 built-ins, no descriptions. To load definitions, the model asked for three tools by exact name. No keyword search ran; it picked from the names. In other captures, Claude's search didn't see the tail of long descriptions either.

So in Claude Code, a name is the whole pitch. `list_changes_since` says what it does; a name like `get_data` doesn't. See [Claude Code tool search, seen from the wire](/blog/claude-code-tool-search-explained/).

## 3. It went for the closest-looking tool

Agents map the request to the tool whose name looks most like it, and call that. On a mock of the same server we added a `get_instructions` tool whose playbooks named the right first step. With no hint to use it, Claude went straight to the most relevant-looking tool in **23 of 24 runs**, Codex in 15 of 24. In a live trial, Claude answered a “review what came in since yesterday” job correctly but paged through every record instead of using the server's “since” tool, in 2 of 2 runs.

The answer may still come out right; the path is longer and more expensive. A start-here tool plus a one-line hint fixed it: 24 of 24 runs in both apps. See [make the agent read your playbook first](/blog/get-instructions-first-24-of-24/).

**Find out why agents pick the wrong tool on your server.**

We run your users' real jobs through Claude Code, Codex and the other apps they use, record every call, and show which causes hit your tools and which fixes remove them.

[Book a pilot →](/#contact)

## 4. The user's word, not the API's

Users talk in the app's screen labels. APIs use their own values. On this server the app showed a tab called “To review”, while the API's status values were different words. Claude Code answers used the screen label 5 times in one round, and the “which project is performing best?” job passed in only **4 of 10 Claude Code runs** across two rounds. In 3 of 5 first-round runs, Claude said the server didn't expose the numbers at all, which was wrong; it did, under the API's word.

Fix: say in the description which screen label each value matches, and accept the label as an alias.

## 5. Heavy overview tools that look like the answer

Asked “how many credits do I have left, is anything running, and how many items are waiting in each project?”, Codex reached for the project-overview tool in **4 of 5 live runs**. That tool returned 14,517 tokens for two projects. The agent needed a handful of numbers. In 2 of the runs it answered from that overview alone and never called the list tool meant for the job; the answer was still right.

Fix: make overview tools return a small summary by default (name, state, counts), with full detail on request.

## 6. Truncated results, then the same call again

For “what's new since yesterday?”, Codex called the activity feed with a limit of 200, twice per run, in **5 of 5 runs**. Each call returned 63.7k–76.5k tokens. The first output was truncated by Codex (“original token count: 67,251”), so the model saw a slice, then called again and filtered in code. Across the wider live test, Codex repeated a call in 13 of 40 runs; Claude Code in 0 of 40.

Fix: smaller default results, a summary line with counts and the next page, and filters for the common questions. See [tool results and errors for agents](/guides/tool-results-and-errors-for-agents/).

## 7. It left MCP for the browser

In an early live pass, a browser skill was installed on the test machine. In **13 of 36 runs** Codex used it to drive the user's signed-in web app instead of calling the MCP server. Nothing was changed, but those runs didn't test the server at all. In a separate live run, the same kind of escape took 781k input tokens. We now block shell and browser access for MCP-only jobs and fail any run that touches them.

For your users this is a real path, not just a test artefact: if MCP looks harder than the web app, agents with a browser will use the web app. See [agents escape to the browser](/blog/agents-escape-to-the-browser/).

**Go deeper:** [Write tool descriptions agents act on](/blog/mcp-tool-naming-for-agent-search/), [Tool annotations agents rely on](/blog/mcp-tool-annotations-destructive-hint/), [Why agents call the same tool twice](/blog/duplicate-tool-calls/), [Why agents don't use your MCP server](/blog/agent-does-not-recognise-mcp-server/).

## How we measured

- **Live:** a 99-tool production MCP server, read-only through an allowlist proxy, 16 Oct 2026. Codex CLI 0.161.0 and Claude Code 2.1.301 with tool search on, 8 jobs × 5 runs per round, two rounds. Every answer read by hand.
- **Captures:** first model requests recorded through a process-scoped intercepting proxy, 16 Oct 2026.
- **Mock:** the same recorded tool list on a local stand-in with a `get_instructions` tool, 232 runs, 18 Oct 2026.
- **Limits:** one server and one small workspace, one model per app. Causes 5 and 6 come from 5-run jobs, so they show what happens, not how often in general. Names in examples are simplified.

Method: [how to test an MCP server with real AI agents](/guides/test-mcp-servers-with-agents/).

## Sources

- Spirit Room live read-only runs, captures and mock runs, 16–18 Oct 2026.
- [Tool-space interference in the MCP era](https://www.microsoft.com/en-us/research/blog/tool-space-interference-in-the-mcp-era-designing-for-agent-compatibility-at-scale/), Microsoft Research.
- [Diagnosing tool-selection reasoning in LLM agents with canary tools](https://arxiv.org/html/2608.04719v1), arXiv.

## FAQ

### Why does my AI agent call the wrong tool?

In our recorded runs the common causes were: the agent never found the server's tools, it chose from tool names alone, it picked the tool closest to the user's words and skipped the intended first step, the user's vocabulary didn't match the API's, an overview tool looked like the answer, a result was truncated, or the agent left MCP for a browser. Vague descriptions are only one of these.

### Why does the agent not use my MCP server at all?

In apps that search for tools, the search can miss. Codex 0.161 never reached a 99-tool server's tools in 8 of 80 live runs, even though the server listed them. Use the words users actually say in tool names and the first line of descriptions, and say what the server is for in the instructions.

### Why does my agent call the same tool twice?

Often because the first result was too big. Codex truncated a 67,251-token result, then called the same tool again and filtered in code. Smaller default results and pagination with a summary avoid the repeat.

### How do I make agents pick the right tool?

Name tools with the words users use, put the essential meaning in the first line of each description, map app labels to API values, keep default results small, and give the agent a start-here tool. Then measure it with repeated runs in the apps your users use.

**Find out why agents pick the wrong tool on your server.**

We run your users' real jobs through Claude Code, Codex and the other apps they use, record every call, and show which causes hit your tools and which fixes remove them.

[Book a pilot →](/#contact)

## Keep reading

- Up[How to optimise your MCP tools by knowing how agents call them](/blog/optimise-mcp-tools-for-agents/)
- Related[When your UI says “To review” and your API says needs\_review: vocabulary mismatches that break agents](/blog/agent-vocabulary-mismatch/)
- Related[Name MCP tools the way users talk: how names-only, regex and BM25 search pick tools](/blog/mcp-tool-naming-for-agent-search/)
- Related[Why agents call the same MCP tool twice (13 of 40 runs) and how to stop it](/blog/duplicate-tool-calls/)
- Related[Your agent test may not be testing your MCP: 13 of 36 runs drove the browser instead](/blog/agents-escape-to-the-browser/)
- Related[When the agent doesn't know your MCP server is the right tool (“Which product do you mean?”)](/blog/agent-does-not-recognise-mcp-server/)