How many MCP tools before the agent loses the thread
The number of tools you expose decides how good your MCP server feels. The observable tiers, three levers to reduce, and what you must never merge.
Nobody talks about this, and it is what decides how good your server feels to use.
An MCP server is not judged on what it makes possible. It is judged on how often the agent picks the right tool on the first try. And that rate collapses well before you have finished exposing your API.
Why the count matters
The model sees your tool list with names and descriptions, and has to choose. Three things degrade as the list grows.
Confusion between neighbouring tools. get_user, get_user_profile, fetch_user_details: a human guesses, a model rolls dice. And it rolls non-deterministically, so your bug is not reproducible.
Context cost. Every tool takes up room, and that room is no longer available for the conversation.
Shared attention. Your server is rarely alone. The user has three or four connected. Your forty tools compete with everyone else's.
That last point is the one people forget. You are not sizing for your server alone, you are sizing for a shared context.
Orders of magnitude
There is no magic threshold, but there are observable tiers.
Under ten well-named tools, selection is reliable. Between ten and twenty, it holds if the names are sharp and the scopes disjoint. Past thirty, selection becomes the main failure mode of your product, regardless of code quality.
A server with twelve clear tools beats one with forty exhaustive ones. That is counterintuitive for a team that spent three years building a complete API.
Three levers to reduce
Group by intent, not by endpoint. Your API has create_draft, update_draft, publish_draft. An agent thinks in terms of "publish this thing". Often one tool with a state parameter beats three tools.
Absorb variation into parameters. search_by_name, search_by_tag, search_by_date are one search tool with optional filters. A model is far better at filling a parameter than at choosing between three neighbouring tools.
Remove what nobody calls. Instrument calls per tool, which the Mcp-Name header makes trivial. A tool never called in three months is not neutral: it takes up room and adds one more way to get it wrong.
What not to merge
Reduction has a limit, and it is sharp.
Never merge read and write. A tool that reads or modifies depending on a parameter cannot be annotated correctly, so the client cannot ask for confirmation before a destructive action. You just removed the only point where a human could say no.
Do not merge different risk levels. Deleting an item and deleting the whole account are not the same tool with a flag.
Do not merge at the cost of an incomprehensible parameter. If the model has to guess a mode out of seven, you moved the problem rather than solving it.
The test that actually measures
Take twenty natural phrasings of things your users want to do. Not your vocabulary, theirs.
For each, run the request in a real client, with at least two other servers connected alongside yours, and note one thing: was the right tool picked first try.
Below 90% is a product problem, not an accident. And the failures tell you exactly which tools look too much alike.
Rerun this test on every tool you add. It is the only way to see the degradation before your users do.
FAQ
Should I expose my whole API?
No, and this is the single most important design decision. Your API serves developers who read docs. Your MCP server serves a model that chooses fast.
What about users who need rare cases?
One well-bounded generic tool often covers the long tail better than twenty specific ones.
Do cacheable lists change anything?
They cut traffic, not confusion. The selection cost stays exactly the same.
Get your tool surface designed
This is the most structural part of building a server, and the one most often skipped. Full build €4,500 to €7,500 depending on scope. On an existing server, the audit quotes the tool surface rework.
Interested? Talk about my MCP server →
Related reading
Got an MCP server to audit?
Five minutes to describe it. I reply within one business day with a first written diagnosis, free of charge.
Get my MCP server audited
