MCP Server Design: Build Tool Interfaces That Agents Actually Use Correctly

You wired up 40 MCP tools. The agent got worse.

It skipped the obvious tool. It invented parameters. It burned three retries on an empty result, then gave up. The protocol was fine. Your tool surface was not.

Model Context Protocol is how agents talk to tools across ChatGPT, Cursor, Gemini, Copilot, VS Code, and a growing set of hosts. Anthropic reported 10,000+ active public MCP servers and 97M+ monthly SDK downloads when it donated the project to the Agentic AI Foundation in December 2025. That is production infrastructure, not a demo format.

When MCP tools underperform, the cause is rarely the protocol. It is tool design for humans and REST APIs reused as tool design for agents. Most weak servers are thin wrappers over existing endpoints. Agents need intent-first tools.

Twin failure modes: bloat and confusion

A typical multi-server stack (GitHub, Slack, Sentry, Grafana, Splunk) can expose about 58 tools and ~55K tokens of definitions before the user says anything. Anthropic has seen tool catalogs climb toward ~134K tokens before anyone optimizes. Fifty-plus tools alone can sit near ~72K tokens.

That is pure context tax. The agent has less room for your actual task, and similar tool names start to collide. Selection quality drops. This is not a hot take. It is the reason Anthropic ships deferred tool loading and tool search.

Anthropic measured the other side of that tradeoff. With Tool Search, a 50+ tool catalog dropped from ~72K tokens to ~8.7K (~85% reduction). Accuracy rose with it (Opus 4 from 49% to 74%; Opus 4.5 from 79.5% to 88.1%). More tools without a loading strategy is not "more capable." It is a noisier menu.

Confusion is the quieter twin. Wrong enums, opaque errors, and database-flavored parameter names force retries. AWS put it plainly in their July 2026 MCP tool design guidance: low baseline cost misleads you when confusion drives churn.

Pattern 1: Intent tools, not endpoint dumps

Circle.so has roughly 80 API endpoints. Sjoerd Tiemensma documented what happens if you wrap them 1:1. A simple question like "most active JS members who skipped recent workshops" becomes a 7-8 call chain. The model has to invent the workflow every time.

The redesign used about 12 intent tools (findSpaces, getSpaceActivity, event filters). Same job became a natural 3-step chain. Aggregation moved server-side. Responses pointed at the next tool ("Use getSpaceActivity with this space ID").

That is the core design move. An MCP tool is a contract between deterministic systems and non-deterministic agents. APIs assume a developer who can reread docs across sessions. Agents are effectively stateless per conversation. Every call has to carry enough signal to finish the job or recover.

If you run community platforms, membership products, or client ops tools, map the same idea: wrap jobs your users actually ask for, not every REST path you already own.

Pattern 2: Names that select cleanly

A field study of roughly 500 MCP servers (ZazenCodes, June 2025) found about 90% snake_case tools, ~95% multi-word, and under 1% camelCase. Package IDs cluster as name-mcp (~40%) or mcp-name (~35%). The draft MCP tools spec allows 1-128 characters, case-sensitive, only A-Za-z0-9_-..

Practical defaults that match the ecosystem:

• Server package: kebab-case plus mcp (billing-mcp or mcp-billing)
• Tools: snake_case, imperative verb + object (get_invoice, list_members, create_ticket)
• Namespace by product when multiple servers share a host (jira_search vs asana_search)
• No conceptual overlap between tools in the same server

Prefer semantic IDs in responses when you can resolve them. Opaque UUIDs force the model to copy strings it does not understand. That is where hallucinated IDs start.

Pattern 3: Schemas that remove guesswork

AWS Prescriptive Guidance for MCP tool design: keep parameter counts around 8 or fewer. Drop rare fields. Use enums and defaults. Name parameters in the language of the task, not the database.

AWS's K-12 content search samples make the failure mode concrete. V1 passed through internal names like content_bucket and discipline. Wrong enum values returned empty sets. Retries cost more than a slightly richer tool. V2 added synonym maps ("quiz" maps to Assessment), cut rare params, and returned educational errors. Later versions deferred context and did more inference on the server.

Schema constraints beat long prose. If the model must invent a free-form string for a closed set of values, you already lost.

Also consider response shape. Anthropic's Slack example cut response size from 206 tokens to 72 with a concise mode. Claude Code caps tool responses at 25,000 tokens by default for a reason. Pagination, truncation notices, and a response_format: concise | detailed switch keep the agent on budget.

One exception to "fewer tools always": destructive work. A single notes tool with an action enum saves tokens, but a misread can turn update into delete. Prefer separate tools for mutate and destroy, plus human approval gates.

Pattern 4: Descriptions, examples, and errors as runtime docs

Anthropic's internal tests found tool-use examples lifted parameter accuracy from 72% to 90%. Schema alone is not enough when formats are ambiguous (date strings, ID prefixes, status codes).

Write descriptions for when to call the tool and how to fill parameters. Map natural-language synonyms to enum values in the description text. Put short examples inline when the format is easy to get wrong.

Then invest in errors. A common Supabase MCP failure mode: the model invents a project_id, the server returns bare {"error":"Unauthorized"}, and the agent stops. It treats the failure as a permission problem instead of a bad ID.

Better:

Project ID proj_abc not found or not permitted. Call list_projects to see valid IDs for this token. Example: list_projects() then get_project(project_id="...").

An error message is the documentation at that moment. Success responses should also steer: return the IDs the next tool needs and name that tool explicitly.

Tiemensma's 90/10 rule is useful here. If recoverable errors can guide the model most of the time, a 2,000-token description full of edge cases usually hurts more than it helps. Spend tokens on defaults and actionable failures, not essay-length tool docs.

The Prompt:

You are reviewing an MCP server before we ship it to agents.

Tool inventory (JSON):
{{TOOL_DEFS}}

Sample API docs (human-oriented):
{{API_SUMMARY}}

Tasks the agent must complete without human help:
1. {{TASK_1}}
2. {{TASK_2}}
3. {{TASK_3}}

For each tool, rewrite:
- name (snake_case, verb_object, no overlap with siblings)
- description (when to use it; synonym map for enums; one usage example if formats are ambiguous)
- input schema (max 8 params; enums + defaults; domain language, not DB columns)
- error templates (what failed, why, next tool + example params)

Then propose a reduced intent tool set: merge multi-step API chains the agent should not invent. Flag any destructive tools that must stay separate.

Output markdown tables:
1) Keep / rename / drop / merge decisions
2) Final tool definitions
3) Three golden eval tasks with expected tool sequences

Why This Works: You force the model to redesign from agent tasks backward, not from OpenAPI forward. The golden sequences become your regression set. The hard limit on parameters and the explicit error contract push the design toward selection accuracy instead of endpoint coverage.

Expected Output:

A keep/rename/merge table, a short intent catalog (often a fraction of the original endpoint count), and eval chains like list_projects → get_project → query_table with concrete parameter examples and failure recovery paths.

Pattern 5: Test with real agents, not only the inspector

Ship order that works in practice:

1. Unit tests and MCP Inspector without an LLM (schema and transport first).
2. Golden multi-step tasks from real workflows, not toy "schedule a meeting with [email protected]" demos.
3. Metrics: first-call correctness, retries, tokens, wrong-tool rate, runtime.
4. More than one model if you can. Descriptions overfit a single model family.
5. Iterate descriptions and schemas from transcripts. Anthropic found Claude-tuned tool defs beat "expert" human wording on held-out tasks. One web-search tool kept appending 2025 to every query until the description was fixed.

Treat the MCP server like a product with evals, not a one-shot wrapper.

When you outgrow a flat tool list

If you run multi-client agency stacks or large internal catalogs, deferred loading and discovery tools stop being optional. Anthropic's code-execution path with MCP can take full definition loads near ~150K tokens down to roughly ~2K with filesystem-style discovery (~98.7% reduction). Programmatic tool calling cut average tokens on complex research tasks from about 43,588 to 27,297 (~37%).

Solopreneurs with a handful of focused servers can ignore that for a while. Teams wiring GitHub + Slack + Notion + Linear + Postgres + Stripe into one agent cannot.

Security note, then back to design: third-party community MCP servers are unreviewed code with credentials. Prefer first-party or audited servers. Scope tokens to the user. Log STDIO servers to stderr only (stdout corrupts the protocol). Least privilege always.

Checklist you can run today

• Count tools and estimate definition tokens. If you are past a few dozen tools, plan discovery or split servers.
• Replace 1:1 API wrappers with intent tools that finish real jobs in fewer calls.
• Rename for snake_case verb_object uniqueness; namespace across products.
• Cap parameters near 8; enums, defaults, domain language.
• Add examples for ambiguous formats; rewrite errors as next-step docs.
• Add concise/detailed (or field selection) for fat responses.
• Build three golden tasks from your real workflows and score wrong-tool rate weekly.

MCP is the agent-facing API layer. The winners will not be the teams that expose the most endpoints. They will be the teams whose tools agents select correctly on the first try.

Want hands-on training on MCP tool design and agent tool-use patterns for your team? Connect with Kief Studio on Discord or schedule a session.