MERLONIX

How Many MCP Tools Is Too Many?

If you're converting a REST API to a Model Context Protocol (MCP) server, the instinctive move is to expose every endpoint. More tools should mean an agent can do more, right?

In practice it's the opposite. Past a certain point, adding tools makes an agent worse at using your server — it picks the wrong tool more often, takes longer to decide, and burns more tokens (and therefore more cost) doing it. Tool count is not a vanity metric. It's a design constraint you have to actively manage, the same way you'd manage the size of a REST API's public surface.

This post covers why that happens, what the failure mode looks like in practice, how to pick a focused tool set, and how Merlonix's converter surfaces the problem instead of letting you ship it blind.

Why More Tools Makes an MCP Server Worse, Not Better

An MCP client works by handing an agent a list of tool definitions — names, descriptions, and input schemas — and asking the model to decide which one (if any) fits the current step of a task. That decision happens at every single turn, over the entire tool list, every time.

A REST API with a well-organized set of endpoints is easy for a human developer to navigate because a human can skim documentation, remember prior use, and narrow down by category before ever making a call. An agent doing tool selection doesn't get that scaffolding for free — it has to reason over the whole list, described only by name and description, and pick correctly with no chance to browse first.

That reasoning step doesn't scale linearly with tool count. It's not "twice the tools, twice the work" — agent tool selection degrades sharply past roughly 40-50 tools. Below that range, an agent generally has enough context to weigh each candidate tool carefully. Above it, tools blur together, similarly-named or similarly-described operations get confused for each other, and the agent's effective accuracy drops even though nothing about the underlying API changed.

This is exactly the kind of thing that's easy to miss if you're building the server, not calling it. The person writing the OpenAPI spec and generating the MCP tools never has to survive the selection step — the calling agent does, on every request, indefinitely.

The Failure Mode in Practice

Tool explosion doesn't show up as a clean error. It shows up as behavior that's frustrating to debug because nothing is technically broken:

  • Wrong tool chosen. The agent calls updateOrderStatus when it meant updateOrderShipment, because both existed in a wall of forty similarly-named operations and the description text didn't do enough to distinguish them.
  • Higher latency. Every additional tool definition is more tokens the model has to read and weigh before it can act. More tools in the list means slower time-to-first-action on every single turn, not just the first one.
  • Higher cost. Those same tokens are billed. A tool list that's 3x larger than it needs to be adds real, recurring cost to every agent session that talks to your server — cost with no corresponding increase in what the agent can actually accomplish.
  • General confusion. Once an agent has picked the wrong tool once in a session, it often compounds — retrying, second-guessing, or asking the user to disambiguate rather than completing the task.

None of this is a bug in the MCP SDK or the agent's model. It's a direct, predictable consequence of tool-list size, and it happens regardless of which agent or client is on the other end.

How to Pick a Focused Tool Set

The fix isn't a smarter agent — it's a smaller, better-curated tool list. A few practical moves:

  • Expose the highest-value read and action operations, not every endpoint. If your OpenAPI spec has 80 operations, most APIs have a much smaller core of things an agent actually needs to call to be useful — the handful of reads and writes that cover the real workflows. Start there.
  • Write descriptions that disambiguate, not just describe. Two tools named getUser and getUserProfile need descriptions that make it obvious which one an agent should reach for and when — not just what each technically returns.
  • Don't expose near-duplicate operations. If your REST API has both a bulk and a per-item version of the same action, consider exposing only one to the agent unless both are genuinely needed.
  • Group by workflow, not by resource. A REST API is often organized by resource (/orders, /customers, /shipments). The tools an agent needs are often organized by task ("process a return", "check an order's status"). Those aren't always the same shape.
  • Reconsider write operations especially. Every write-capable tool (POST/PUT/PATCH/DELETE) is both a selection-accuracy risk and a blast-radius risk if the agent picks wrong. Fewer, clearer write tools beat many overlapping ones.
  • Revisit the list as it grows. A tool surface that started focused can creep past the 40-50 range one convenience endpoint at a time. Treat tool count as something you monitor, not something you set once.

How the Merlonix Converter Handles This

The free API-to-MCP converter turns an OpenAPI 3.x or Swagger 2.0 spec (JSON, pasted or fetched by URL) into a runnable MCP server: each operation becomes a tool, with the operationId as the tool name, the summary as the tool description, and parameters/requestBody compiled into a JSON-Schema inputSchema.

Because tool explosion is a real failure mode and not just an aesthetic concern, the converter builds two guardrails directly into that generation step:

  • A hard cap. Generation is capped at 100 tools (MAX_MCP_TOOLS = 100).
  • A warning below the cap. If your API's operation count is over the point where agent tool selection is known to degrade, the converter warns you — well before you hit the hard cap — so you can decide which operations actually belong in the agent-facing surface instead of finding out after an agent starts picking the wrong ones in production.

This is the same self-check Merlonix ran on its own API: converting /v1/openapi.json (13 paths) produced 23 correctly-named MCP tools — comfortably inside the range where tool selection stays reliable.

Tool Count in the MCP-Readiness Grade

The converter also runs an MCP-readiness grade (A-F) on the server it generates, across seven dimensions. Tool count is one of them, alongside:

  • Tool poisoning — scanning every tool's name and description for injection patterns (a hidden instruction smuggled into an OpenAPI summary that could hijack the calling agent). This one caps the grade outright, because an unsafe server should never read as ready regardless of anything else.
  • Auth posture — no auth vs. static API keys vs. OAuth 2.1.
  • Write-verb exposure — how many tools can modify data (POST/PUT/PATCH/DELETE), since those carry more risk if an agent selects the wrong one.
  • Untyped inputs — how many parameters lack a proper schema, which makes both validation and agent reasoning about the tool harder.
  • Missing descriptions — operations with no description at all. Agents rely on the description to choose a tool; a tool with no description is a tool an agent can only guess about.
  • Tool-surface size — whether the generated list is small enough for an agent to choose well, using the same roughly-40-50 threshold as the general guidance above.

The grade exists so you find out about a tool-count or tool-poisoning problem at generation time — not after an agent has been calling your server in production for a month.

A Practical Checklist

Before you ship an MCP server generated from a REST API:

  • Count your generated tools. If you're near or past 40-50, decide what to cut before you decide what to add.
  • Check for near-duplicate tools that cover the same underlying action.
  • Confirm every tool has a real, disambiguating description — not just the operation's technical summary.
  • Review every write-capable tool (POST/PUT/PATCH/DELETE) specifically; these carry more risk than reads if mis-selected.
  • Confirm inputs are properly typed, not left as untyped/free-form parameters.
  • Scan tool names and descriptions for anything that looks like an embedded instruction rather than a description (tool poisoning).
  • Re-run the check after you add new operations — tool count creeps.

From Generation to Ongoing Monitoring

Getting the tool count and readiness grade right at generation time is the first checkpoint, not the last one. Once your MCP server is live, tool definitions can drift — an endpoint gets added, a schema changes, a description gets edited — and that's the kind of silent change that breaks every agent already calling it. Merlonix's MCP-server health monitor runs a real MCP handshake (initialize + tools/list) on a schedule and alerts on downtime, a failed handshake, latency regression, or tool-schema drift, including a change in tool count.

For the full generate-validate-monitor lifecycle — turning a REST API into an MCP server, grading it, and then watching it — see the pillar guide: Convert a REST API to an MCP Server.

→ Try it now: free API-to-MCP converter with the readiness grade → See also: MCP-server health monitoring → Related: Convert a REST API to an MCP Server