Your MCP tool descriptions are failing your agent

Your agent is calling the wrong tool. Not because the model is bad, and not because your prompt is broken. The description on your search_customer_records tool says "searches customer records" and that is technically correct, and completely useless to a model trying to decide which of four similar tools to call right now.

A February 2026 study analyzing real-world MCP tool descriptions found that 97.1% of them contain at least one quality problem. This is not a niche edge case. It is the norm. And those problems translate directly into wrong tool selections, inflated token budgets, and agents that look like they work in demos but quietly fail under load.

Let me walk through what the research found and what you can actually do about it.

What the research found

The striking result is how widespread the problem is: only 2.9% of real-world MCP tool descriptions are clean. The rest have at least one pattern that harms agent behavior. Most have several.

The researchers identified these problems by analyzing thousands of tool definitions from publicly deployed MCP servers, then measuring how each problem type affected task success rates, partial completion rates, and token usage on a benchmark suite of agentic tasks.

The impact is not subtle. Fixing description quality improved task success by a median of 5.85 percentage points and partial goal completion by 15.12%. For a customer service agent handling hundreds of conversations a day, that difference matters in deflection rate and in customer experience.

There is a complication worth knowing upfront: better descriptions do not always mean faster agents. The same research found that augmenting tool descriptions increased execution steps by 67.46% in some cases and actually hurt performance on 16.67% of tasks. More information in a description helps the model decide when to use a tool, but it can also make the model overthink a simple call.

The right mental model: descriptions should be exactly long enough to disambiguate the tool from its neighbors. No longer.

The tool description smells

A "smell" in this context is a quality problem that reduces agent accuracy or wastes tokens. Here are the ones that show up most often in production deployments.

Vague purpose statements. "Searches customer records" does not tell the agent when to use this tool. Does it search by name? By phone number? By account ID? By conversation history? What does it return? A model choosing between four search tools with equally vague descriptions will pick one semi-randomly.

Missing parameter context. The description says customer_id: string and nothing else. But is that a UUID, an integer, an email address, or an internal system ID? What happens if the customer does not exist? The model cannot infer this from the type annotation alone.

Ambiguous names. Tools named process, handle, query, or fetch tell the agent nothing about what they actually do. When you have process_ticket, process_refund, and process_escalation, the model must read every description carefully to disambiguate. Verb-noun patterns like create_support_ticket, issue_refund, and escalate_to_agent make the distinction clear from the name alone, before the model reads a single character of the description.

Missing edge case guidance. Many descriptions are written for the happy path and leave the agent to improvise when things go wrong. What should it do if the tool call returns empty results? What if the API returns a rate limit error? The result is inconsistent behavior that is hard to debug because it looks different every time.

Undeclared side effects. A tool that creates a calendar entry or sends a Slack notification should say so explicitly. If the description only mentions what the tool returns, the agent might call it speculatively -- "I'll just check" -- without realizing it is triggering real-world actions.

Context-free parameter types. status: string as a parameter description is useless when the valid values are open, pending_customer, resolved, and closed. Enum-like parameters need their valid values listed, ideally with a note about which ones are most common.

Missing when-not-to-use guidance. Some tools have natural counterparts and the agent needs to know the difference. If you have search_order_history and get_order_details, clarify: one is for finding relevant orders, the other is for fetching full detail on a known order ID. Without this, the agent defaults to whichever it encounters first.

The context bloat problem

Tool descriptions do not just affect accuracy. They consume tokens, and at production scale this becomes a serious constraint.

Every tool schema gets injected into the agent's context window on each request. That includes the name, description, and full parameter schema for every tool the agent can access. In a minimal setup with a handful of tools, this is negligible. In a production deployment, it is not.

Connecting just three MCP servers -- GitHub, Slack, and Sentry -- with roughly 40 tools consumed 143,000 of a 200,000-token context window. That is 72% of the available budget burned on tool metadata before the agent processed a single character of the user's message.

Add a fourth server for your CRM. Add a fifth for your knowledge base. Add a sixth for scheduling. You are not building an exotic setup. You are building a standard CX agent that handles realistic business tasks. And you have just made it architecturally unable to handle long conversations because the context is full of schemas.

This is why teams building agents with 50+ tools hit a wall that does not show up in early testing. The dev prototype connects three tools. The production system connects twelve. Token budget is gone before the customer's third message loads. The tool explosion problem is architectural, and description quality is one layer of the solution.

How to write descriptions that work

The goal of a tool description is not to explain everything the tool can do. It is to give the agent enough signal to make the right selection decision, without making it think harder than necessary.

Here is a template that works for CX agent tools:

[What this tool does in one verb-object sentence]. Use when [the condition that makes this the right choice].
[Key parameter notes: valid values, format, what happens on edge cases].
[What the result contains and what to do with it].
[Side effects, if any].

Applied to the search_customer_records example from the opening:

Before:

name: "search_customer_records"
description: "Searches customer records"
parameters:
  - query: string (the search query)

After:

name: "search_customer_records"
description: "Finds customers by name, email, or phone number. Use when you have a partial identifier and need to locate a customer account before taking any action. Returns a list of matching customer objects with IDs -- pass the ID to get_customer_profile for full details. Does not search by order number or ticket ID; use search_order_history for that. If multiple results return, ask the user to confirm before proceeding."
parameters:
  - query: string (name, email address, or phone number in any format; partial matches are supported)
  - limit: integer (max results to return; defaults to 5, max 20)

The second version is longer. That is fine, because every sentence answers a question the agent might have. Notice what it does:

• States the use case explicitly
• Disambiguates from get_customer_profile with a forward reference
• Tells the agent what it does NOT cover and where to go instead
• Handles the edge case of multiple matches
• Clarifies parameter format

Parameter descriptions deserve special attention because they are often the worst part of real-world tool schemas. Type annotations alone are not descriptions.

// Weak: type annotation only
{ name: "customer_id", type: "string", description: "The customer ID" }
 
// Strong: format and behavior
{
  name: "customer_id",
  type: "string",
  description:
    "UUID identifying the customer account. Required. Returns a 404 error if no customer exists with this ID. Get it from search_customer_records if you only have a name or email.",
}
 
// Weak: enum with no values listed
{ name: "status", type: "string", description: "The ticket status" }
 
// Strong: valid values with context
{
  name: "status",
  type: "string",
  description:
    "Filter tickets by status. Valid values: 'open', 'pending_customer', 'pending_agent', 'resolved', 'closed'. Use 'open' and 'pending_agent' together to find tickets waiting on your response.",
}

This level of description takes longer to write once. It pays off every time the agent calls the right tool on the first try rather than retrying after calling the wrong one.

Tool Search: the architectural answer to bloat

Better descriptions help accuracy. They do not solve the context bloat problem. For that, you need a different loading strategy.

Tool Search -- which became generally available in early 2026 -- lets agents query for relevant tools by semantic similarity rather than loading every schema upfront. The agent describes what it is trying to do, Tool Search finds the matching tools, and only those schemas enter the context window for that request.

Early benchmarks show an 85% reduction in token usage compared to static loading. For a 200,000-token context window, that means spending roughly 20,000 tokens on tool schemas instead of 143,000 -- freeing space for longer conversations, richer customer context, and more nuanced reasoning.

The tradeoff is discoverability. When you load all tools upfront, the agent can browse and find unexpected solutions. With Tool Search, the agent finds only tools that match what it already knows it needs. A tool with a poorly described purpose will not surface in search -- which is another reason description quality matters regardless of loading strategy.

Here is how a production CX agent might use dynamic tool loading via the MCP runtime in Chanl:

import Chanl from "@chanl/sdk";
 
const chanl = new Chanl({ apiKey: process.env.CHANL_API_KEY });
 
// Instead of loading all schemas upfront:
// const tools = await chanl.mcp.listTools();
 
// Query for relevant tools based on current task context:
const relevantTools = await chanl.mcp.searchTools({
  query: "find customer account update contact information",
  limit: 5,
  sessionId: session.id,
});
 
// Only matching schemas enter the context
const response = await agent.complete({
  messages: conversation.messages,
  tools: relevantTools.schemas,
});

The result is an agent that can access hundreds of tools without the context filling up on schemas before the user's message has room.

Making descriptions searchable

Tool Search changes how you should write descriptions in one important way: your tools now need to be discoverable by semantic search, not just readable by a model that sees everything at once.

When a model sees all your tools, it can compare and reason across them. When it searches for tools on demand, it needs to find the right one from a description that matches the semantic intent of what it is trying to do.

A few adjustments that help:

Include synonyms for common customer intents. If customers might say "check my balance," "see what I owe," or "view my account balance," your get_account_balance tool description should include those phrasings: "Returns the current balance and payment due date. Use when the customer asks about their balance, what they owe, or upcoming payment amounts."

Reference the business domain. get_order_details is less discoverable than "Fetches full details for a specific order including line items, shipping status, and fulfillment timeline." The second version has more hooks for semantic matching.

Name tools for customer intent, not API shape. Your internal API might have GET /v2/customers/{id}/orders. The tool name should be get_customer_orders, not orders_v2_get or call_customer_orders_endpoint.

Cross-reference related tools. If search_order_history and get_order_details work together, say so in both descriptions. An agent that knows to call search first, then detail lookup, will perform the task in fewer steps than one figuring out the relationship by trial and error.

What to do this week

If you are running MCP-connected agents in production right now, here is where to start.

Audit your most-called tools first. Export your tool usage logs and find the five tools your agent calls most often. Read their descriptions cold -- without knowing what the tools do. Do the descriptions tell you when to use each one? Do they tell you what valid parameter values look like? If not, rewrite those first.

Then look for description drift. Tool descriptions get written once and rarely updated. If a tool's behavior changed -- new parameters, new valid values, different output format -- the description probably did not change with it. Stale descriptions are a persistent source of agent confusion that is hard to catch in testing because the description was accurate when you wrote the test.

Third, measure token consumption per request. If more than 30-40% of your context is going to tool schemas, you have hit the threshold where Tool Search or tool curation starts to pay off. You can measure this directly with the monitoring features in Chanl alongside conversation outcomes.

The description quality work is not glamorous. But it is probably the highest-return debugging you can do on a production MCP agent. Two hours of description rewriting typically catches failure modes that weeks of model tuning cannot reach, because the issue was never the model -- it was the signal you were giving it.

El briefing de Signal

Un email por semana. Cómo los equipos líderes de CS, ingresos e IA están convirtiendo conversaciones en decisiones. Benchmarks, playbooks y lo que funciona en producción.

Subscribe

500+ líderes de CS e ingresos suscritos