Blog / 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.
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.
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.
- 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.
- 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.
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.
Go deeper: Name tools the way users talk, Why agents call the wrong tool, Claude Code can't see your MCP tools?.
What to do
- Put your product's name where search looks: the server name, tool names, and the first line of descriptions.
- Use the user's words, including screen labels, not just API terms. See UI words vs API values.
- 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.
- Add a start-here tool and point to it from every tool's first line.
- Test vague requests as well as precise ones, per app, and count runs with zero calls.
- 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.
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.