{
  "post": {
    "title": "MCP tool design: fewer, safer, testable tools",
    "url": "https://bardak.ai/posts/mcp-tool-design",
    "updated": "2026-10-29T18:55:57.159Z"
  },
  "citation": "MCP tool design: fewer, safer, testable tools, Ivan Bardak, bardak.ai, https://bardak.ai/posts/mcp-tool-design",
  "datasets": [
    {
      "key": "mcpverse-task-success-as-the-tool-set-grows",
      "title": "MCPVerse: task success as the tool set grows",
      "type": "chart",
      "source": "Lei et al., MCPVerse (arXiv 2508.16260, v2, October 2025), Table 2",
      "caption": "With every tool loaded, all three models lost 29% to 36% of the success rate they had with the minimum set. A moderate set did not always hurt: two models did as well or better with 220 tools than with the minimum. Gemini's largest setting used prompt-based function calling because of the API's tool limit.",
      "csv": "https://bardak.ai/data/mcp-tool-design/mcpverse-task-success-as-the-tool-set-grows.csv",
      "header": [
        "model",
        "Only the servers needed",
        "32 servers (220+ tools)",
        "65 servers (552 tools)"
      ],
      "rows": [
        [
          "Claude 4 Sonnet",
          "62.3",
          "62.4",
          "44.2"
        ],
        [
          "Qwen3-235B-2507",
          "44.8",
          "53.2",
          "31.6"
        ],
        [
          "Gemini 2.5 Pro",
          "48.7",
          "45.3",
          "31.4"
        ]
      ]
    },
    {
      "key": "context-used-by-tool-definitions-in-a-five-server-setup",
      "title": "Context used by tool definitions in a five-server setup",
      "type": "chart",
      "source": "Anthropic, Introducing advanced tool use on the Claude Developer Platform (November 2025)",
      "caption": "About 55,000 tokens in total for 58 tools. Anthropic also reports the most common failures in such setups: the wrong tool, or the wrong parameters, especially between tools with similar names.",
      "csv": "https://bardak.ai/data/mcp-tool-design/context-used-by-tool-definitions-in-a-five-server-setup.csv",
      "header": [
        "server",
        "Tokens (thousands)"
      ],
      "rows": [
        [
          "GitHub (35 tools)",
          "26"
        ],
        [
          "Slack (11 tools)",
          "21"
        ],
        [
          "Sentry (5 tools)",
          "3"
        ],
        [
          "Grafana (5 tools)",
          "3"
        ],
        [
          "Splunk (2 tools)",
          "2"
        ]
      ]
    },
    {
      "key": "mcp-tool-annotations",
      "title": "MCP tool annotations",
      "type": "benchmarkTable",
      "source": "Model Context Protocol specification, version 2026-07-28: Tools and schema",
      "caption": "A tool with no annotations is treated as writing, destructive, not idempotent and open to the outside world. The specification says clients must treat annotations as untrusted unless the server is trusted.",
      "csv": "https://bardak.ai/data/mcp-tool-design/mcp-tool-annotations.csv",
      "header": [
        "Annotation",
        "Default",
        "Meaning",
        "What the client should do"
      ],
      "rows": [
        [
          "readOnlyHint",
          "false",
          "The tool does not modify its environment",
          "Allow without confirmation, if the server is trusted"
        ],
        [
          "destructiveHint",
          "true",
          "The tool may make destructive changes, not only additions",
          "Ask the user before calling it"
        ],
        [
          "idempotentHint",
          "false",
          "Repeating the call with the same arguments has no further effect",
          "Safe to retry after a timeout only if true"
        ],
        [
          "openWorldHint",
          "true",
          "The tool talks to external systems, such as the web",
          "Treat its output as untrusted content"
        ]
      ]
    },
    {
      "key": "mcp-tool-review-checklist",
      "title": "MCP tool review checklist",
      "type": "benchmarkTable",
      "source": "",
      "caption": "",
      "csv": "https://bardak.ai/data/mcp-tool-design/mcp-tool-review-checklist.csv",
      "header": [
        "Check",
        "Why",
        "Pass when"
      ],
      "rows": [
        [
          "Count",
          "Accuracy falls and context fills as the list grows",
          "Under 20 tools active per turn, or on-demand loading beyond that"
        ],
        [
          "Task, not endpoint",
          "Agents misuse chains of CRUD calls",
          "Each tool completes a user task in one call where possible"
        ],
        [
          "Names",
          "Similar names cause the wrong tool",
          "Prefixed by service or resource, no near-duplicates"
        ],
        [
          "Description",
          "Small wording changes swing accuracy",
          "States purpose, inputs, limits and an example"
        ],
        [
          "Inputs",
          "Free text invites invented values",
          "Typed, with enums for known values"
        ],
        [
          "Results",
          "Raw records waste context",
          "Names and needed fields only, paginated, with a concise option"
        ],
        [
          "Errors",
          "The model needs to recover",
          "Validation errors returned as tool errors with a fix"
        ],
        [
          "Side effects",
          "Clients decide when to ask the user",
          "Annotations set honestly; destructive tools gated"
        ],
        [
          "Scope",
          "Least privilege",
          "Tools listed and allowed according to granted scopes"
        ],
        [
          "Tests",
          "Demos hide failure rates",
          "Evaluation set with repeated runs, re-run on every change"
        ]
      ]
    },
    {
      "key": "appraising-the-evidence",
      "title": "Appraising the evidence",
      "type": "benchmarkTable",
      "source": "",
      "caption": "",
      "csv": "https://bardak.ai/data/mcp-tool-design/appraising-the-evidence.csv",
      "header": [
        "Evidence",
        "Strength",
        "Main limitation"
      ],
      "rows": [
        [
          "MCP specification and docs",
          "Authoritative for what clients and servers must do",
          "Says what is allowed, not what works best"
        ],
        [
          "Benchmarks (LongFuncEval, MCPVerse, MCP-Zero)",
          "Independent, repeatable",
          "Synthetic tasks; some tables have inconsistencies the authors have not fixed"
        ],
        [
          "Vendor guidance (Anthropic, OpenAI)",
          "Practice from teams running agents at scale",
          "Written about their own models and products"
        ],
        [
          "My reviews",
          "Direct experience across client projects",
          "One practitioner, not measured systematically"
        ]
      ]
    }
  ]
}