MCP tool design: fewer, safer, testable tools

When I review an MCP server, the first thing I count is tools. A typical first version has thirty or forty of them, one per REST endpoint: list_customers, get_customer, update_customer, list_orders, and so on. It works in the demo. Then the agent starts picking the wrong tool, filling in IDs it made up, and the context window fills with tool definitions before the user has typed anything.

Tool design is the part of an agent you control completely, and it turns out to matter a great deal. This post collects what the specification, the model vendors and independent benchmarks say about it, and turns that into a review checklist.

The short answer: give the agent fewer tools, each built around a task rather than an endpoint; describe them precisely; declare what they change; return short, meaningful results; and test them with real tasks, as you would any API. Benchmarks show accuracy falling as the tool list grows, and every major vendor now recommends keeping the active set small.

More tools, worse choices

Several independent benchmarks have measured what happens when an agent sees more tools. IBM researchers grew the tool catalogue from 49 to 741 tools and saw accuracy drop by 7% to 85% depending on the model (LongFuncEval). In the MCP-Zero study, Claude 3.5 Sonnet picked the right tool 97.6% of the time from a small, relevant set and 69.2% of the time from the full set of 48 (Fei et al. 2025). MCPVerse ran real MCP servers in three settings, from only the servers each task needs up to all 65 servers and 552 tools:

The second cost is context. Anthropic reported that a common setup of five MCP servers exposes 58 tools whose definitions take about 55,000 tokens, before the conversation starts (Anthropic, November 2025):

The vendors' own guidance has converged:

• OpenAI suggests aiming for fewer than 20 functions available at the start of a turn, as a soft limit (function calling guide).
• Anthropic says tool selection degrades once more than 30 to 50 tools are available and recommends loading tools on demand beyond about ten (tool search docs).
• The MCP documentation suggests budgeting tool definitions at 1% to 5% of the context window, and warns that loading everything up front wastes tokens, adds latency and degrades performance (client best practices).

On-demand tool search helps: in Anthropic's MCP evaluations it lifted one model from 79.5% to 88.1%. But it is a fix for a large catalogue, not a reason to build one. The cheaper fix is on the server side: fewer, better tools.

Design tools around tasks, not endpoints

Anthropic's engineers wrote that, for their SWE-bench agent, they spent more time optimising tools than the prompt (Building effective agents). Their tool-writing guide (Writing effective tools for agents) turns that into rules I now use in every review:

• One tool per task. A schedule_event tool instead of list_users, list_events and create_event; search_logs instead of read_logs. The agent should not have to orchestrate your data model.
• Verbs, not tables. publish_article and schedule_article beat update_record with a status field.
• Names that separate. Prefix by service or resource (crm_search_contacts, billing_search_invoices). The MCP specification asks clients that combine servers to disambiguate names, for example with a server prefix.
• Descriptions written for a new colleague. Small changes in wording make large differences. In one of Anthropic's examples, the agent kept adding the year to every search query until the description was fixed.
• Short, meaningful results. Return names and the fields the next step needs, not UUIDs and every column. A concise response format cut one of their results from 206 tokens to 72. Paginate and truncate by default.
• Errors the model can act on. The MCP specification returns input validation errors as tool results flagged as errors, so the model can correct itself. Say what was wrong and what a valid value looks like.

Make the risky parts explicit

Since March 2025, MCP has let servers describe what a tool does to the world through annotations (MCP specification, tools). The defaults are deliberately pessimistic:

Annotations are hints for the client, not security controls; a malicious server can lie. The control belongs in the server and in authorization. Three features of the current specification help:

• Output schemas. A tool can declare the shape of its result; the server must conform to it and clients should validate it. That turns a vague text blob into a contract you can test.
• Tools filtered by scope. Since July 2026, a server may return only the tools the caller's granted scopes permit. An agent with read access should not even see delete_invoice. See delegated access and AI agent authentication for the scope design, and MCP specification changes, explained for what each revision changed.
• A human who can say no. The specification says there should always be a human in the loop able to deny a tool invocation. Make destructive tools require that approval in the client, not in the prompt.

For writes, I add one rule of my own: read before write. Reads return a revision token and writes require it, so a stale update fails loudly instead of overwriting someone's work.

Test tools like an API

Anthropic's guide treats evaluation as the core of tool design: generate realistic tasks, some needing dozens of calls, keep a held-out set, and track not only success but the number of calls, tokens and tool errors. That is how you find the tool the agent keeps misusing, or the description it misreads.

1. Build 30 to 100 tasks from real requests, each with a checkable outcome.
2. Run each task several times. One success proves little; see the reliability numbers in Agentic AI from demo to production and the latest numbers in my tracker of AI agent benchmarks.
3. Log every call with arguments, errors and tokens, and review the failures weekly.
4. Re-run the set whenever a tool, a description or the model changes.
5. Add contract tests for input and output schemas, as for any public API.

The tool review checklist

How much weight this evidence deserves

Tools are one of the five parts of an AI agent architecture that decide whether an agent reaches production; the others are identity, retrieval, reversibility and measurement.

Sources

• Model Context Protocol specification, version 2026-07-28: Tools.
• Model Context Protocol documentation: Client best practices.
• Anthropic (December 2024). Building effective agents.
• Anthropic (September 2025). Writing effective tools for agents.
• Anthropic (November 2025). Introducing advanced tool use on the Claude Developer Platform.
• Anthropic. Tool search tool documentation.
• OpenAI. Function calling guide.
• Kate et al. (2025). LongFuncEval: Measuring the effectiveness of long context models for function calling. arXiv:2505.10570.
• Lei et al. (2025). MCPVerse: An expansive, real-world benchmark for agentic tool use. arXiv:2508.16260.
• Fei, Zheng and Feng (2025). MCP-Zero: Active tool discovery for autonomous LLM agents. arXiv:2506.01056.