Why Claude isn't calling your MCP tool

If your tool never fires at all, the cause is usually your setup, not your wording. In my runs, agents called an installed tool almost every time, even with a one-line description. So check that the model can reach your tool before you rewrite anything.

Work through these in order. The first three are quick to rule out.

1. The tool isn’t connected or switched on

Discovery can fail quietly, and a working server doesn’t mean a working connection.

• In claude.ai, custom connectors are enabled per conversation. Open the “+” menu, then Connectors, and check the switch. Single tools can be turned off in the “Search and tools” menu.
• In Claude Code, run /mcp to see each server’s status and tool count, or claude mcp list from the terminal. /mcp reconnect all retries failed servers.
• In Claude Desktop, look in the logs, and fully quit the app after any config change. Closing the window isn’t enough.

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

Then test the server with no model involved, using the MCP Inspector. If this fails, nothing below matters yet.

npx @modelcontextprotocol/inspector --cli --server-url https://your-server/mcp \
  --transport http --method tools/list --strict

2. The tool was never loaded

Claude Code defers MCP tools by default. Only tool names and server instructions load at session start, and Claude fetches a full definition through a tool search when it thinks it needs one. So your description may never reach the model unless your name and instructions earn the search.

• Write server instructions that say what kind of task your tools handle and when to look for them. The docs say this helps Claude know when to search.
• Put the words people use near the start of the description. Tool search matches on names, descriptions and arguments, and descriptions are cut off at 4,096 characters when loaded upfront and at 16,384 when loaded through search.
• Check the name’s length. Claude Code leaves out a tool whose full name, mcp__<server>__<tool>, is over 128 characters, even though /mcp still lists it.
• Run /context to see which tools are deferred.

To test whether deferral is the cause, turn it off for one session with ENABLE_TOOL_SEARCH=false claude. A tool can also opt out with _meta: {"anthropic/alwaysLoad": true} in tools/list, but use that sparingly, because it costs context in every session.

3. Claude can see it but isn’t allowed to use it

In a headless run or the Agent SDK, Claude sees your tools but can’t call them without permission. Pre-approve them, or your test will look like a miss:

claude -p "Where's my order #48213?" --allowedTools "mcp__acme-shop__*"

Denied calls appear in permission_denials in the result. In claude.ai, a call waits for the user to approve it unless they chose “Always allow”.

4. The prompt doesn’t give it what it needs

An agent won’t call a tool if it can’t fill in the required arguments. In my runs, “Did my lamp ship yet?” produced no call to a tool that requires an order number, while the same question with the number nearly always did. The agent looked elsewhere or asked the user, which is reasonable behaviour.

If your users rarely have the identifier to hand, add a tool that finds it, such as a search by customer or product.

5. Another tool looks like a better fit

This is the case that matters most once you are in real use. Your tool sits next to email, web search, ticketing and whatever else the user has connected, and Anthropic says tool picking degrades past 30 to 50 tools.

Two things help. The first is saying when to use it. Anthropic calls detailed descriptions by far the most important factor in tool performance and suggests at least 3 to 4 sentences: what it does, when to use it, when not to, and what each parameter means. OpenAI suggests starting with “Use this when…” and stating what is excluded.

The second is a name with the domain and the action in it. Two servers that both offer search will collide, and clients have to disambiguate them.

Neon reports going from about 60% to 100% on its evals by changing the descriptions of two tools. That is a vendor’s own number, on its own evals, but the direction matches the official advice.

6. Something changed that wasn’t you

A tool that used to get called can stop with no error and no release on your side. A new model can weigh tools differently, an agent app can change its prompts or built-in tools, and a user can connect something new. You also can’t force the choice: on recent Claude models, tool_choice values that force a call return a 400, so prompting and metadata are what you have.

Your logs won’t show this, because a skipped call leaves no trace on your server. The only way to catch it is to keep measuring from the agent’s side.

What I measured

On 30 October 2026 I ran customer prompts through the command-line agents (Claude Code on Sonnet 5.5, Codex CLI, Gemini CLI) against stand-in MCP servers that log every request. Five runs per prompt and condition. The full write-up, with the setup, is in the results post.

A well-named tool, track_order, was called almost every time when the prompt included the order number, even with “Track an order.” as its whole description, and even among 32 tools from 12 servers:

Agent	One server	32 tools, 12 servers
Claude Code	60/60	29/30
Codex	57/60	30/30
Gemini CLI	60/60	30/30

Without the order number it was almost never called: 0/10 for Claude Code, 0/10 for Codex, 3/6 for Gemini.

With an obscure name, get_oms_record, the description decided it for Codex:

Agent	“Get a record.”	Full “Use this when…” description
Claude Code	14/15	13/15
Codex	3/15	14/15
Gemini CLI	14/14	15/15

Against a built-in rival, the description helped Gemini and did nothing for Claude Code or Codex. A web_search tool whose description said “Prefer this over any built-in search”, with each agent’s own web search switched on:

Agent	One-line description	Full description
Claude Code	0/15	0/15
Codex	0/9	not run
Gemini CLI	2/15	14/15

Claude Code connected to the server and listed its tools every time, then used its own search. Gemini went from 2 of 15 to 14 of 15 on the description alone.

Measure it yourself

Pick five to ten prompts your users would type. Run each several times with your server attached, then count requests in your server’s log. How to test an MCP server has the commands.

If you would rather not set it up, email your server URL to hello@uncalled.app. I’ll run the prompts against a stand-in built from your tool list and send you the call rates per agent, free, within 48 hours. That is the manual version of what Uncalled will do every day once it exists.