--- title: Why Agents Don't Use Your MCP Server ('Which Product?') description: Connected, yet unused: Codex never reached a 99-tool MCP server in 6 of 40 runs and asked 'which platform?' with 0 calls. Why it happens and what fixes it. canonical: https://spiritroom.app/blog/agent-does-not-recognise-mcp-server/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/agent-does-not-recognise-mcp-server/ for agents. Index: /llms.txt [Blog](/blog/) / [Onboard agents through MCP](/guides/onboard-agents-through-mcp/) # When the agent doesn't know your MCP server is the right tool (“Which product do you mean?”) Your MCP server is installed, connected, and healthy. The user asks about your product by name. The agent replies “which product do you mean?” or opens a browser, and never calls a tool. It isn't a connection problem. The model never linked the user's words to your server. Here's what we measured and what helps. Leonid Bugaev · Published 21 Oct 2026 **TL;DR** - **Connected but unused:** Codex never reached a 99-tool server's tools in 6 of 40 live runs (7–29%); Claude Code reached them in 40 of 40. - **“Which platform?”**: in a small live trial Codex asked which platform the user meant and made 0 calls. - **Vague requests are the risk:** on a mock, Codex asked “which product do you mean?” in 2 of 2 runs with no hint from the server. - **A short hint helped:** with the full start-here recipe, both apps called the right tool first on vague requests in 4 of 4 runs (51–100%), and called nothing on off-topic requests (0 of 15). - **Some of it the server can't fix:** Codex's first request doesn't name your server at all. [What it looks like](#what)[Why it happens](#why)[What fixed it on a mock](#mock)[What to do](#fix)[How we measured](#how-we-measured)[FAQ](#faq) ## What it looks like We tested a 99-tool production MCP server, read-only, with 8 real jobs × 5 runs per app. The server was connected and listed all its tools every time. Claude Code: reached the tools *40/40* Codex: reached the tools *34/40 (6 never did)* In the 6 Codex runs, it said no connector for the product was available and tried a browser instead. Over two rounds it was 8 of 80. The misses clustered on three jobs: “which group is doing best” (3 of 5), “plan and usage” (2 of 5) and “status of automations” (1 of 5). When Codex did reach the tools, it answered correctly in 34 of 34 runs. In a smaller live trial, with no agent skills installed, one Codex run went further: it didn't realise the request was about the product at all, asked **“which platform?”**, and made 0 calls. ## Why it happens Recognition comes before discovery. The model has to connect the user's words, often a product name or a screen label, to a server it may not have seen yet. user names the productmodel links it to a server?searches toolscalls one - **Codex** in code mode doesn't name MCP servers in its first request. The model sees your tools only after it chooses to search them. If it doesn't search, nothing your server sends is seen. See [how Codex finds MCP tools](/blog/how-codex-finds-mcp-tools/). - **Claude Code** shows tool names up front, so a product name in tool names gives it something to match. It reached the tools in every run. - **Vague requests** make it worse: “help me get more out of the product” gives the search little to match on. **Find out if agents recognise your server.** We run your users' requests, vague ones included, through Claude Code, Codex and the other apps they use and measure how often the agent reaches your tools. [Test your MCP →](/#contact) ## What fixed it on a mock On a mock with the same 99 tools, we added a start-here tool and tested vague and off-topic requests. | Setup | Vague request: right first call | Codex asked “which product?” | | --- | --- | --- | | Start-here tool only | Claude Code 2/4, Codex 1/4 | 2 of 2 runs | | Plus a one-line hint in the instructions | – | 1 of 1 run | | Full recipe (instructions hint, hint in every tool description, Claude always-load flag) | Claude Code 4/4, Codex 4/4 (51–100% each) | 0 | On off-topic requests, no agent called the server in any setup: **0 of 15 runs**. The hints didn't make agents reach for the server when it wasn't relevant. The vague samples are small, so treat 4 of 4 as direction, not proof. Details: [make the agent read your playbook first](/blog/get-instructions-first-24-of-24/). **Go deeper:** [Name tools the way users talk](/blog/mcp-tool-naming-for-agent-search/), [Why agents call the wrong tool](/blog/why-agents-call-the-wrong-tool/), [Claude Code can't see your MCP tools?](/blog/claude-code-mcp-tools-not-found/). ## What to do 1. **Put your product's name where search looks**: the server name, tool names, and the first line of descriptions. 2. **Use the user's words**, including screen labels, not just API terms. See [UI words vs API values](/blog/agent-vocabulary-mismatch/). 3. **Start the instructions with what the server is for**, in one line: “This is the X server; use it for questions about …”. Keep it short: [how long MCP server instructions should be](/blog/mcp-server-instructions-length/). 4. **Add a start-here tool** and point to it from every tool's first line. 5. **Test vague requests** as well as precise ones, per app, and count runs with zero calls. 6. **Know the limit:** if an app never searches, the server can't reach the model. Document how users can name the server in their request. More on onboarding: [onboard agents through your MCP server](/guides/onboard-agents-through-mcp/). ## How we measured - **Live:** a 99-tool production MCP server, read-only, Codex CLI 0.161.0 and Claude Code 2.1.301, 8 jobs × 5 runs, 16 Oct 2026; a second Codex round for the 8 of 80 figure. - **Small live trial:** 3 jobs × 2 conditions × 2 runs, with and without agent skills, 16 Oct 2026. - **Mock:** the same recorded tool list with a start-here tool, 232 runs including vague and off-topic requests, 18 Oct 2026. - **Limits:** ranges are 95% Wilson intervals; vague-request samples are 1–4 runs per setup. Job wording is generalised. ## FAQ ### Why is my agent not using my MCP server? If the server is connected, the usual reason is recognition: the model didn't link the user's request to your server. In apps that search for tools, the search may never run or may miss your tools. Codex never reached a connected 99-tool server in 6 of 40 live runs. ### Why does the agent ask which product I mean? Because nothing it has seen yet ties the product name to your tools. In Codex code mode the first request doesn't name MCP servers; the model only sees your tools after it decides to search. On vague requests it sometimes asks instead. ### How do I make agents recognise my MCP server? Use your product's name and your users' words in the server name, tool names and the first line of descriptions; start the instructions with what the server is for; and add a start-here tool. In our mock, that recipe got the right first call on vague requests in 4 of 4 runs per app. ### Will hints make agents call my server when it's not relevant? Not in our test: on off-topic requests no agent called the server in any setup, 0 of 15 runs. **Find out if agents recognise your server.** We run your users' requests, vague ones included, through Claude Code, Codex and the other apps they use and measure how often the agent reaches your tools. [Test your MCP →](/#contact) ## Keep reading - Up[How to onboard AI agents through your MCP server (guide)](/guides/onboard-agents-through-mcp/) - Related[How Codex finds MCP tools: code mode and ALL\_TOOLS](/blog/how-codex-finds-mcp-tools/) - Related[Why AI agents call the wrong tool: 7 causes we saw in recorded runs](/blog/why-agents-call-the-wrong-tool/) - Related[Claude Code can't see your MCP tools? Check the proxy and --tools settings first](/blog/claude-code-mcp-tools-not-found/)