98% of MCP Tools Don't Tell AI Agents When to Use Them
We analyzed 78,849 tools across 15,923 MCP servers and skills. The results are sobering.
When an AI agent connects to an MCP server, it sees a list of tools — each with a name, description, and parameter schema. That description is the *only* information the agent has to decide which tool to use, what arguments to pass, and what to do when things go wrong.
We built SpiderRating to measure how well MCP tool descriptions serve AI agents. Here's what we found:
The Numbers
| What agents need | What they get |
|---|---|
| "What does this tool do?" (action verb) | 68% of tools have one |
| "When should I use this tool?" (scenario trigger) | 2% of tools have one |
| "What format should this parameter be?" (param docs) | 3% of tools have them |
| "Can you show me an example?" (param examples) | 7% of tools have them |
| "What do I do if this fails?" (error guidance) | 2% of tools have it |
98% of tools don't tell the AI agent when to use them. The agent has to guess.
Why This Matters
In the API era, a developer would read the README, check the examples, browse Stack Overflow, and gradually learn an API. They had minutes to hours.
An AI agent has ~100 milliseconds to pick the right tool from a list of 50+. Its only input: name and description. No README. No examples. No Stack Overflow.
A tool description like "Search for items" is obvious to a human — but an AI agent needs "Use this when the user wants to find, browse, or discover products. Not for order lookup — use get_order instead."
When AI picks the wrong tool, users blame "AI being dumb." The real issue: developers write descriptions for humans, not for agents.
The Description Score Gap
The gap between MCP servers and skills is dramatic:
- 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 — most developers write a one-line description and call it done.
Documentation Maturity Levels
We classified every tool into maturity levels:
- L1 Minimal: Has a name (baseline)
- L2 Basic: Has an action verb (~68% of tools)
- L3 Structured: Has scenario triggers or parameter docs (~5%)
- L4 Agent-Ready: Has error guidance (~2%)
- L5 Production-Grade: Complete documentation (<1%)
Most MCP servers are stuck at L2. They tell agents *what* but not *when*, *how*, or *what if*.
The Path Forward
The good news: this is fixable. The cheapest improvement any MCP developer can make: add one sentence explaining when to use each tool. It takes 30 seconds.
- Scenario triggers: "Use this when the user wants to..." (+2-3 points)
- Parameter documentation: "date: ISO-8601 format (YYYY-MM-DD)" (+1-2 points)
- Error guidance: "Returns 409 if resource already exists. Retry with a different name." (+1-2 points)
SpiderShield (our open-source scanner) can analyze your MCP server and show exactly which tools need improvement. SpiderRating provides the ecosystem-wide quality signal that's been missing.
Explore the Data
Rate your server for free with our online scanner — just paste a GitHub URL.
pip install spidershield && spidershield scan /path/to/server
- Browse the full leaderboard to see top-rated servers
- See the most secure servers by security score
- Read our scoring methodology to understand how SpiderScore works
- Check the best descriptions to see what good looks like
- View the full server directory with 15,923 rated tools
---
*SpiderRating measures agent-safe usability — how well tool descriptions serve AI agents making autonomous decisions. It's intentionally strict because the stakes are higher when machines, not humans, are interpreting your documentation.*