Pin + research: is our MCP tool shape (one tool per resource, action enum) still best practice?

[leggetter]

Why

We are about to ship v3.0.0 (#348), which is the first release in a while that can change MCP tool names without a compatibility cost — the hookdeck_ → gateway_ rename is already in it, and clients must re-grant tool permissions either way.

That makes it the right and possibly only cheap moment to ask whether the shape of our tools is right, not just their names. This issue pins exactly what we have today so any redesign is measured against a fixed reference rather than a memory of one.

This issue is a pin and a research tracker. It proposes no change yet.

Tagged in git as v3.0.0-pin-pre-tool-shape-review (a965637).

The design under review

We use one tool per resource, with an action enum parameter, rather than one tool per operation. gateway_connections with action: "list" | "get" | "pause" | … instead of gateway_list_connections, gateway_get_connection, gateway_pause_connection.

The original reasoning was context economy: fewer tool definitions in the model's context. Every tool a server registers costs tokens in every request for the whole session, whether used or not.

The question is whether that trade still holds, and whether we have taken it too far.

Where we are — Event Gateway

Tool	Actions
gateway_connections	list, get, pause, unpause, create, upsert, update, delete, enable, disable
gateway_sources	list, get, create, upsert, update, delete, enable, disable
gateway_destinations	list, get, create, upsert, update, delete, enable, disable
gateway_transformations	list, get, create, upsert, update, delete, run
gateway_events	list, get, raw_body, retry, cancel, mute
gateway_requests	list, get, raw_body, events, ignored_events, retry
gateway_issues	list, get, update, dismiss
gateway_attempts	list, get
gateway_metrics	events, requests, attempts, transformations

Plus platform tools hookdeck_login, hookdeck_projects, and gateway_help.

9 product tools, 55 actions.

Where we are — Outpost

Tool	Actions
outpost_tenants	list, get, upsert, delete, token, portal
outpost_destinations	list, get, create, update, delete, enable, disable
outpost_events	list, get, retry
outpost_attempts	list, get
outpost_config	get, set, custom_domain_get, custom_domain_set, custom_domain_delete
outpost_metrics	events, attempts
outpost_publish	publish
outpost_topics, outpost_destination_types, outpost_status	list / get

The cost this shape carries

Collapsing operations into one tool means the schema is the union of every action's parameters, and the model has to infer which apply to the action it picked. Parameter count per Gateway tool:

Tool	Params
gateway_events	25
gateway_requests	19
gateway_connections	10
gateway_issues	10
gateway_metrics	10
gateway_transformations	9
gateway_sources	8
gateway_destinations	8
gateway_attempts	7

gateway_events carries 25 parameters across 6 actions. Only a handful are meaningful for any one action — raw_body needs an id and nothing else, while list uses most of the filters. Nothing in the schema expresses that, so correctness rests on the description text and the model's inference.

There is also a second-order effect: some parameters are renamed between the MCP surface and the API (connection_id → webhook_id, filter_status → status), which exists partly to keep one flat namespace workable across several actions.

What the research needs to answer

1. Consensus position. What do Anthropic, OpenAI and the MCP spec authors actually recommend on tool granularity? Is one-tool-per-operation the default advice, and how strong is it?
2. Is context economy still the binding constraint? It motivated this design. With larger context windows, prompt caching, and client-side tool filtering, does it still dominate — or has the cost moved to model accuracy in action selection and parameter validity?
3. Evidence, not opinion. Are there benchmarks or evals measuring tool-count and schema-complexity effects on tool-selection accuracy? (Berkeley Function Calling Leaderboard, τ-bench, MCP-specific evals, published internal evals.)
4. What comparable servers do. GitHub, Stripe, Linear, Sentry, Supabase, Cloudflare, Notion — one tool per operation or consolidated? Do they use toolsets / dynamic discovery / filtering instead of consolidation to manage context?
5. The fat-schema question specifically. Is a 25-parameter union schema a known anti-pattern, and what is recommended instead — narrower tools, per-action schemas, nested objects, oneOf/anyOf variants?
6. Migration cost if we change. We would be renaming and re-shaping tools inside the same major that already renames them. Doing both at once is cheaper than doing them in separate majors.

Constraint on any outcome

Whatever we conclude, hookdeck_login and hookdeck_projects stay platform-prefixed and shared across product servers. That is settled and not part of this review.

Related

• v3.0.0: Outpost support, Gateway MCP write mode, and the gateway_ tool rename #348 — the v3.0.0 PR this pins
• Rename Gateway MCP product tools to a gateway_ prefix (major) #352 — the gateway_ rename (absorbed into v3.0.0: Outpost support, Gateway MCP write mode, and the gateway_ tool rename #348)
• Epic: v3.0.0 — Outpost support, Gateway MCP write mode, and the gateway_ rename #354 — v3.0.0 epic
• RFC: top-level hookdeck mcp exposing tools by selected project type #351 — RFC: a top-level hookdeck mcp exposing tools by project type; any tool-shape change interacts with it
• MCP: cross-project fan-out for read tools #353 — cross-project fan-out for read tools

[leggetter]

Conclusion: keep the action-enum shape, split two tools

Research done across three angles — vendor guidance, published benchmarks, and the tool definitions of ~15 production MCP servers read from source. Summary below; the finding that decides it is in §3.

Recommendation: keep one-tool-per-resource with an action enum. Split gateway_events and gateway_requests. Change nothing else.

1. The vendors directly contradict each other, so this can't be settled by citation

Anthropic recommends our exact pattern, by name, in the Claude Platform "Define tools" docs:

Consolidate related operations into fewer tools. Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.

OpenAI recommends against it, in the Apps SDK MCP guide:

Create one tool for each distinct action... Prefer focused operations such as list_projects, get_project, and update_project over one tool with many unrelated modes.

The MCP specification says nothing about granularity — no normative or advisory statement. There is no neutral arbiter.

Worth separating two things that get conflated: Anthropic's engineering blog advice about consolidation is about collapsing a multi-call workflow into one semantic operation (schedule_event). That is not the action-enum pattern. Only the platform docs page endorses the enum itself.

2. Our original rationale (context economy) has been overtaken — but that doesn't change the answer

Both vendors shipped tool search (GA; on by default in Claude Code). Only tool names load at session start and just the tools needed get expanded. Anthropic's published fix for tool-definition token cost is deferral, and nowhere do they offer consolidation as the answer to it.

So the context saving we bought by consolidating is now largely provided by clients for free — except on surfaces without deferral (older clients, some hosted deployments, most third-party MCP hosts). That's a long-tail compatibility argument, not a headline one.

It doesn't flip the decision, because consolidation turns out to be justified on other grounds (§3), but we should stop citing context economy as the primary reason.

3. The deciding finding: parameter overlap, not action count

From reading production tool definitions, the predictor of whether an action enum works is whether the actions share a parameter set:

• GitHub pull_request_read — 9 methods, 7 params (all share owner/repo/pullNumber). Clean and cheap.
• GitHub projects_write — 10 methods, 26 params. The most expensive tool GitHub ships: ~2,091 tokens against a median tool of ~203.

Our tools split cleanly along that line:

Tool	Actions	Params	Verdict
gateway_connections	10	10	fine — high overlap
gateway_sources	8	8	fine
gateway_destinations	8	8	fine
gateway_transformations	7	9	fine
gateway_issues	4	10	fine
gateway_metrics	4	10	fine
gateway_attempts	2	7	fine
gateway_events	6	25	outlier
gateway_requests	6	19	outlier

Industry median is 3–5 parameters (measured across GitHub 117 tools, Sentry 54, Grafana 108, MongoDB 53, Atlassian 98, Neon 35, Supabase 32). Only two tools in that entire sample exceed 25 params, and both are their server's single most expensive tool.

In gateway_events, only id is shared. The other 24 parameters are list filters — every description ends in (list). raw_body, retry, cancel and mute each need one parameter and are shown twenty-five.

The best available measurement of that cost: WildAGTEval (Amazon/KAIST/Pitt/UIUC, arXiv 2601.00268, Jan 2026) ranked 60 real-world API-complexity dimensions and found irrelevant information in the API specification was the worst, reducing strong-model performance by 27.3%. Supporting it, ComplexFuncBench shows models reach 79–80% call accuracy but only 61% task success, with parameter-value errors the largest error class. And ~97% of MCP token cost is inputSchema, not descriptions — schema width is what we actually pay for.

4. Why not split everything

• Tool-count degradation is real, with a measured elbow at 40–60 tools (production catalog of 584 tools; 16–23pp F1 degradation). A full one-tool-per-operation split puts Gateway alone at 58 tools, and 88 with both servers loaded — walking into the other failure mode.
• Consolidation is a measured 2–3× saving on schema tokens. GitHub keeps consolidated tools as the default and granular as opt-in behind feature flags.
• The one direct general-vs-specific A/B available (ClickHouse ClickStack, Opus 4.6, Jul 2026) favoured specific tools by 7–20pp — but it compared purpose-built tools against a generic SQL interface, which is a different axis from ours.
• No published A/B of "action enum" vs "many narrow tools" exists. Anyone claiming otherwise is citing opinion. The MCP community's own discussion on it closed without consensus.

5. On read/write splits, and why we don't need one

GitHub does split by risk class — issue_read/issue_write, pull_request_read/pull_request_review_write, projects_get+projects_list/projects_write — consolidating within a risk class and never across it, which keeps readOnlyHint truthful.

The mechanical reason they need it does not apply to us. Most servers filter read-only mode by the annotation:

// GitHub, pkg/inventory/filters.go
if r.readOnly && !tool.IsReadOnly() { /* drop tool */ }

For them, a tool spanning list and delete must be readOnlyHint: false and therefore disappears in read-only mode — you lose the ability to list at all. We rebuild the action enum per mode instead, so our read-only tools contain only read actions and correctly report ReadOnlyHint: true. That is Grafana's approach (mode-specific variants registered under one name), which the survey identifies as the one clean way to consolidate across the read/write boundary.

The residual cost is narrow: in --allow-write mode no tool carries ReadOnlyHint: true, so reads can't be auto-approved and a client gating on destructiveHint will prompt on list. That is over-warning — the safe direction — inside a session an operator explicitly opted into with --allow-write. The spec is explicit that annotations are untrusted hints and not a security boundary; our enforcement correctly lives in the flag, the schema gate, and RequireWrite.

Also worth recording: there is no schema idiom anywhere for argument-conditional risk — no if/then, no dependentRequired, in any surveyed server. The real-world answers are conservative over-approximation (GitHub) or runtime privilege downgrade (Supabase runs execute_sql inside a read-only transaction). Sentry omits annotations entirely across all 54 tools.

6. Things we should not do

• Don't build dynamic tool discovery. GitHub shipped --dynamic-toolsets in April 2025, kept it in permanent beta, never enabled it on the remote server, and deleted it in PR #2512 (May 2026). Search+execute only pays off at hundreds of operations (PostHog: 1 tool wrapping 861; Cloudflare: 2 tools over 2,500+ endpoints).
• Don't split by read/write across the board. See §5.
• Don't treat context economy as the justification for the current shape. See §2.

7. Cheaper wins that come first

Both measured, neither breaking, neither needs to be in 3.0.0:

• Tool-use examples: Anthropic measured 72% → 90% on complex parameter handling — precisely our failure mode on wide tools.
• Descriptions: Neon went 60% → 100% on tool-selection success from description and prompt work alone, with no code change. Separately, a study of real MCP servers found 97.1% of tool descriptions carry at least one "smell", with Opaque Parameters at 84.3%.

Outcome

• Shape stays. hookdeck_login / hookdeck_projects stay platform-prefixed, as already settled.
• gateway_events and gateway_requests get split — tracked separately.
• Pinned at v3.0.0-pin-pre-tool-shape-review (a965637) if we ever want to diff against this state.

Key sources

• Anthropic — Define tools · Advanced tool use · Writing effective tools for agents
• OpenAI — Build an MCP server · Define tools
• MCP — Tools specification 2026-07-28
• WildAGTEval — Beyond Perfect APIs (arXiv 2601.00268)
• ComplexFuncBench (arXiv 2501.10132) · LongFuncEval (arXiv 2505.10570) · Scaling Enterprise Agent Routing (arXiv 2606.17519)
• GitHub MCP — tool consolidation (Discussion #1182) · granular tools PR #2306 · dynamic toolsets removal PR #2512
• Notion — hosted MCP server · Cloudflare — Code Mode

[leggetter]

Follow-up opened as #360 — split gateway_events and gateway_requests. That is the only structural change this research supports; the other seven Gateway tools stay as they are.

[leggetter]

Research complete; conclusion posted above. The one structural change it supported (#360) is implemented and shipping in v3.0.0 — see #354. Follow-up from the same review is #363.

Closing: the question is answered and the pin is no longer needed (the tag was removed; a965637 is the commit if a diff against the pre-review state is ever wanted).