Your API Is Not Your MCP Tool · Roland Huß↓<br>Skip to main content<br>Roland Huß
Table of Contents<br>Table of Contents
The most natural thing to do when building an MCP server is to mirror your existing API. You have a REST endpoint for creating users, so you make a create_user tool. You have one for listing orders, so you make a list_orders tool. Fifteen endpoints become fifteen tools, each one a thin wrapper that translates JSON-RPC to HTTP and passes the response back.<br>It works. The agent can call the tools, the tools return data, and everything looks fine in your test harness. Then you connect it to a real conversation with twenty other MCP servers loaded, and the agent starts picking the wrong tools, hallucinating parameter values, and burning half its context window on tool definitions it never uses.<br>The problem isn’t MCP. The problem is that APIs were designed for a fundamentally different consumer. A developer reads documentation, bookmarks the three endpoints they need, and writes code that calls them in the right order with the right parameters. An LLM sees every tool definition at once, every parameter description, every schema. It has to pick the right tool from that pile on every turn, and each definition costs tokens whether the tool gets called or not.<br>Anthropic’s engineering team put it directly: “A common error we’ve observed is tools that merely wrap existing software functionality or API endpoints.” AWS frames the same insight as two failure modes: “bloat” (tool definitions consuming context on every call whether used or not) and “confusion” (models picking wrong tools as context fills). Both companies arrived at the same conclusion from different directions. MCP tool design is not an API design problem. It’s a context engineering problem.<br>How many tools is too many<br>There’s no single number, but the data points tell a consistent story.<br>Tool-selection accuracy drops below 90% between 10 and 15 tools for Claude Haiku 4.5, and between 20 and 30 tools for Sonnet 4. Bigger models tolerate more tools, but none of them are immune. GitHub’s MCP server grew to over 100 tools after a month of community contributions, degraded agent capabilities, and got cut back to about 40.<br>The pattern is the same in every case: teams start by exposing everything, then discover that more tools means worse results. The reduction isn’t about removing functionality. It’s about consolidating related operations into higher-level tools that match what users actually ask for.<br>Consider a project management API with separate endpoints for creating issues, assigning them, setting priority, adding labels, and linking to epics. That’s five tool definitions in the context window and a workflow that requires the agent to sequence five calls correctly. A single manage_issue tool that accepts an action parameter and handles the orchestration internally gives the model one decision point instead of five. The agent’s job becomes “pick the right tool” rather than “pick the right five tools in the right order.”<br>AWS calls this the progression from V1 (raw API passthrough) through V6 (agent-as-tool), and their conclusion is worth quoting: no single version wins across all dimensions. Raw passthrough is easiest to build but hardest for agents to use. Fully orchestrated tools are great for agents but expensive to maintain. The right level depends on how complex the workflow is and how often the agent needs fine-grained control over individual steps.<br>The per-server tool count is only half the equation. In any real setup, you’re connecting multiple MCP servers at once, and their tool definitions stack. Every server you add pushes more definitions into the context window. Being selective about which servers you connect matters at least as much as being selective about which tools each server exposes.<br>Claude Code’s configuration hierarchy helps with this on the client side. You define MCP servers at user, project, or directory scope, with project-level configs overriding what’s active for a specific codebase. A Kubernetes project gets your cluster tools, a documentation project gets your writing tools, and nothing bleeds across. cc-setup wraps this in a terminal UI for managing servers, permissions, and plugins per project from a central registry.<br>Parameters that help instead of confuse<br>The number of parameters matters almost as much as the number of tools. AWS recommends roughly eight or fewer per tool, with an important caveat: if bundling related operations requires more than eight parameters, prioritize the bundling over the parameter count. A single tool with twelve well-described parameters usually outperforms three tools with four parameters each, because the model makes one tool-selection decision instead of three.<br>But parameter count is the easy part. The harder lesson is that parameter naming and...