Why does the model never call my MCP tool?

An MCP client selects tools almost entirely from their name and description in tools/list. If the description is empty, one word, or doesn't say what the tool does, when to use it and what it returns, the model can't match it to a user request — so it silently skips it. Vague descriptions, missing inputSchema, and overloaded servers with dozens of similar tools are the top causes.

How should I write MCP tool descriptions?

Write each description as one or two sentences stating what the tool does, when an agent should use it, and what it returns. Name tools with clear verbs (search_orders, not handler3). Give every input a typed inputSchema with per-field descriptions. Avoid near-duplicate tools; consolidate or disambiguate them so the model isn't forced to guess.

MCPPulse

Guide · Updated July 2026 · 6 min read

Why your MCP tools aren't being called

Direct answer: Your server connects, tools/list returns your tools, and yet the model never uses them. The cause is almost always metadata, not transport: the model picks tools from their name and description, so a vague or empty description makes a tool invisible. Fix descriptions, input schemas and tool count — then verify with a scan.

How an agent actually chooses a tool

When a user asks an agent to do something, the model doesn't read your source code. It sees the tools/list output — each tool's name, description and inputSchema — and matches the request against those strings. If nothing clearly matches, it does nothing or answers from memory. Your tool can be perfectly implemented and still never fire.

The three usual culprits

1. Empty or vague descriptions

Compare:

// invisible to agents
{ "name": "run", "description": "" }
{ "name": "getData", "description": "gets data" }

// gets selected
{ "name": "search_orders",
  "description": "Search a customer's past orders by email or order ID. Use when the user asks about order status, history, or a specific purchase. Returns order id, date, items, total and fulfillment status." }

State what it does, when to use it, and what it returns. That last clause matters — the model plans multi-step chains and needs to know a tool's output shape.

2. Missing or loose input schemas

Every tool needs a valid inputSchema (JSON Schema) with typed fields and per-field descriptions. Without it the model can't construct a valid call, so it avoids the tool. Mark required fields; don't leave everything optional and untyped.

3. Too many near-duplicate tools

Twenty tools named get_x, fetch_x, list_x with overlapping descriptions force the model to guess and it guesses wrong (or abstains). Consolidate. A handful of clearly-differentiated tools outperforms a sprawling, ambiguous surface.

Verify the fix

MCP Pulse reports the exact percentage of your tools that have meaningful descriptions and flags the ones that don't — so you can see the problem the way an agent sees it, and confirm the fix landed.

See which of your tools are invisible

Free scan shows tool-description coverage in 10 seconds.

Scan my server →