98% of MCP Tools Don't Tell AI Agents When to Use Them

#devops #security #ai #opensource

We analyzed 78,849 tool descriptions across 15,923 MCP servers and AI skills. The results explain a lot about why AI agents feel "dumb."

TL;DR: Only 2% of tools tell the AI agent when to use them. Only 3% document their parameters. This is why AI agents pick the wrong tool — and it's fixable.

The Numbers

What AI Agents Need	What They Get
"What does this tool do?" (action verb)	68% have one
"When should I use this tool?" (scenario trigger)	2% have one
"What format should parameters be?" (param docs)	3% have them
"Can you show me an example?" (param examples)	7% have them
"What happens if it fails?" (error guidance)	2% have it

98% of tools don't tell the AI agent when to use them. The agent has to guess from the tool name and a vague description.

Why This Is a Security Problem

As a Reddit user pointed out in response to our State of MCP Security report:

"The missing usage guidance number is the one that doesn't get enough attention. When a tool doesn't tell the agent when to use it, the agent has to infer from context. That inference step is exactly where a poisoned tool description or injected instruction can redirect behavior."

Missing scenario triggers aren't just a quality problem — they're an attack surface.

The Description Score Gap

MCP servers: average description score 3.13/10
Skills: average description score 5.67/10

Skills score higher because the SKILL.md format encourages structured descriptions. MCP servers have no such convention.

Better Descriptions = Better Scores

Description Score	Average Overall Score	Count
Low (0-3)	4.55	3,751
Mid (3-5)	5.39	2,665
Good (5-7)	5.32	7,976
Great (7-10)	6.47	1,531

Tools with great descriptions score 42% higher overall.

What a Good Tool Description Looks Like

Bad (98% look like this):

name: "search"
description: "Search for items"

Good (what AI agents need):

name: "search_products"
description: "Search the product catalog by keyword, category, or price range.
  Use this when the user asks to find, browse, or look up products.
  Returns up to 20 results sorted by relevance.
  Parameters:
    query (string, required): Search keywords
    category (string, optional): Filter by category name
  Errors:
    - Returns empty array if no matches
    - Returns 429 if rate limited — wait 60 seconds"

The Paradigm Shift

Most developers write tool descriptions for humans. But AI agents don't have common sense:

Human-to-Human: "Search for items" → human infers the rest
Human-to-Agent: "Search products by keyword. Use when user wants to find
                 or discover products. Not for order lookup — use
                 get_order instead."

We're still learning how to write for non-human intelligence.