What makes a tool list readable to an agent
We scored thousands of MCP tool surfaces for how easily an LLM can pick the right tool. The same four mistakes come back again and again.
An agent never sees your documentation. It sees a list of tool names, one-line descriptions, and a JSON schema of parameters. That is the entire briefing. If the right tool is not obvious from that, the agent picks the wrong one — or asks the user a question it should not have needed to ask.
We run every readable tool surface in the catalog through an evaluation and score it. Reading thousands of those, the failures cluster.
1. Tools that overlap
Two tools that could plausibly answer the same request is the most expensive mistake, because the agent has no tiebreaker. If you have search_docs and find_document, one of them should say what it is for that the other is not.
2. Parameters without meaning
A parameter named query with type string tells the agent nothing. What goes in it — a keyword, a question, an ID? Is it case sensitive? What happens when it is empty? The schema is where that belongs, not the README.
3. No examples on the ambiguous ones
Most tools do not need an example. The one that takes a free-form object, or a filter expression, or a domain-specific identifier absolutely does. In our evaluations, "lacks usage examples" is one of the most frequent weaknesses — and it is nearly always about one specific tool, not the whole server.
4. Silent constraints
Rate limits, maximum result counts, execution timeouts, whether a call costs money. An agent that does not know the limit will hit it. The servers that score highest are the ones that state these plainly in the description.
The short version
- Distinct names that imply distinct jobs.
- Every parameter described in terms of what to put in it.
- Examples on the tools a human would ask about.
- Limits written down where the agent will actually read them.
None of this requires more tools. Most of it requires fewer, described better.
See how a server scores