Why
Follows the research conclusion in #359. That review found our one-tool-per-resource, action-enum shape is sound and should stay — with two exceptions.
The predictor of whether an action enum works is whether the actions share a parameter set, not how many actions there are. GitHub's pull_request_read has 9 methods and 7 parameters because every method takes owner/repo/pullNumber; it is cheap and clean. GitHub's projects_write has 10 methods and 26 parameters and is the single most expensive tool they ship — roughly 2,091 tokens against a median tool of ~203.
Two of our tools are the second case.
| Tool |
Actions |
Params |
Shared across all actions |
gateway_events |
6 |
25 |
id only |
gateway_requests |
6 |
19 |
id only |
Every other Gateway tool is at or below 10 parameters and stays as it is.
In gateway_events, 24 of the 25 parameters are list filters — every one of their descriptions ends in (list). raw_body, retry, cancel and mute each need a single id and are shown all 25. gateway_requests is the same shape: list carries the filters while get, raw_body, events, ignored_events and retry need an id.
For scale: the median parameter count across ~500 tools in surveyed production MCP servers (GitHub, Sentry, Grafana, MongoDB, Atlassian, Neon, Supabase) is 3–5. Only two tools in that entire sample exceed 25 parameters, and both are their server's most expensive. Ours would sit in the top 1%.
The evidence
- 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, cutting strong-model performance by 27.3%. A schema where ~24 of 25 fields cannot apply to the chosen action is that failure, concretely.
- ComplexFuncBench (arXiv 2501.10132): models reach 79–80% call accuracy but only 61% task success, with parameter-value errors the largest error category. Once the tool set is small, argument generation is where models fail — not tool selection.
- ~97% of MCP token cost is
inputSchema, not descriptions. Wide schemas are what we actually pay for, on every request.
Proposed shape
Split each of the two along the seam that already exists — list versus everything else — rather than fully per-operation.
gateway_events →
gateway_events — list only, keeps the ~22 filtersgateway_event — get, raw_body, retry, cancel, mute; parameters id plus whatever retry/cancel/mute genuinely need
gateway_requests →
gateway_requests — list only, keeps the filtersgateway_request — get, raw_body, events, ignored_events, retry
This keeps the enum pattern (so it stays consistent with the other seven tools and with Anthropic's guidance), removes the irrelevant-parameter problem for the five actions that only need an id, and adds two tools rather than ten. Gateway goes from 9 product tools to 11 — nowhere near the measured 40–60 degradation elbow.
Naming is the open question. Plural-for-list / singular-for-one-record reads naturally but is a subtle distinction for a model to hold; gateway_events / gateway_events_detail, or gateway_events_search / gateway_events, are alternatives. Worth a quick eval rather than a preference — see below.
Also settle while we are here: gateway_requests currently declares status twice and has both id and request_id. Whatever the split, that should be cleaned up.
Do it in 3.0.0
This changes tool names and shapes, and 3.0.0 already renames every product tool (hookdeck_ → gateway_, #352). Users re-grant tool permissions once either way. Doing it in a later major means a second forced migration for no additional benefit.
If it does not make 3.0.0, it should wait for 4.0.0 rather than ship as a minor.
Cheaper things that come first
Both are measured, neither is breaking, and neither needs to be in this issue's scope — but they target the same failure mode and cost far less:
- Tool-use examples. Anthropic measured 72% → 90% on complex parameter handling. That is exactly the failure a wide tool produces.
- Descriptions. Neon went 60% → 100% on tool-selection success from description and prompt work alone, no code change. A study of real MCP servers found 97.1% of tool descriptions carry at least one "smell", Opaque Parameters at 84.3%.
If we do these first and the split still looks worthwhile, we will have better evidence for it.
Worth measuring
No published A/B of "action enum" versus "narrow tools" exists — #359 looked and found none. This split is a small, well-scoped chance to produce one: hold a set of tasks fixed, build both arms for a single resource, and score action selection and per-argument correctness separately.
That would tell us whether the 27.3% proxy actually transfers to our surface, and would settle the naming question with data instead of taste.
Tasks
Related
Why
Follows the research conclusion in #359. That review found our one-tool-per-resource,
action-enum shape is sound and should stay — with two exceptions.The predictor of whether an action enum works is whether the actions share a parameter set, not how many actions there are. GitHub's
pull_request_readhas 9 methods and 7 parameters because every method takesowner/repo/pullNumber; it is cheap and clean. GitHub'sprojects_writehas 10 methods and 26 parameters and is the single most expensive tool they ship — roughly 2,091 tokens against a median tool of ~203.Two of our tools are the second case.
gateway_eventsidonlygateway_requestsidonlyEvery other Gateway tool is at or below 10 parameters and stays as it is.
In
gateway_events, 24 of the 25 parameters arelistfilters — every one of their descriptions ends in(list).raw_body,retry,cancelandmuteeach need a singleidand are shown all 25.gateway_requestsis the same shape:listcarries the filters whileget,raw_body,events,ignored_eventsandretryneed an id.For scale: the median parameter count across ~500 tools in surveyed production MCP servers (GitHub, Sentry, Grafana, MongoDB, Atlassian, Neon, Supabase) is 3–5. Only two tools in that entire sample exceed 25 parameters, and both are their server's most expensive. Ours would sit in the top 1%.
The evidence
inputSchema, not descriptions. Wide schemas are what we actually pay for, on every request.Proposed shape
Split each of the two along the seam that already exists —
listversus everything else — rather than fully per-operation.gateway_events→gateway_events—listonly, keeps the ~22 filtersgateway_event—get,raw_body,retry,cancel,mute; parametersidplus whateverretry/cancel/mutegenuinely needgateway_requests→gateway_requests—listonly, keeps the filtersgateway_request—get,raw_body,events,ignored_events,retryThis keeps the enum pattern (so it stays consistent with the other seven tools and with Anthropic's guidance), removes the irrelevant-parameter problem for the five actions that only need an id, and adds two tools rather than ten. Gateway goes from 9 product tools to 11 — nowhere near the measured 40–60 degradation elbow.
Naming is the open question. Plural-for-list / singular-for-one-record reads naturally but is a subtle distinction for a model to hold;
gateway_events/gateway_events_detail, orgateway_events_search/gateway_events, are alternatives. Worth a quick eval rather than a preference — see below.Also settle while we are here:
gateway_requestscurrently declaresstatustwice and has bothidandrequest_id. Whatever the split, that should be cleaned up.Do it in 3.0.0
This changes tool names and shapes, and 3.0.0 already renames every product tool (
hookdeck_→gateway_, #352). Users re-grant tool permissions once either way. Doing it in a later major means a second forced migration for no additional benefit.If it does not make 3.0.0, it should wait for 4.0.0 rather than ship as a minor.
Cheaper things that come first
Both are measured, neither is breaking, and neither needs to be in this issue's scope — but they target the same failure mode and cost far less:
If we do these first and the split still looks worthwhile, we will have better evidence for it.
Worth measuring
No published A/B of "action enum" versus "narrow tools" exists — #359 looked and found none. This split is a small, well-scoped chance to produce one: hold a set of tasks fixed, build both arms for a single resource, and score action selection and per-argument correctness separately.
That would tell us whether the 27.3% proxy actually transfers to our surface, and would settle the naming question with data instead of taste.
Tasks
gateway_eventvsgateway_events_detailvs alternatives)gateway_eventsinto list and single-record toolsgateway_requestslikewisestatusand theid/request_idoverlap ingateway_requestsgateway_helptopics and the README tool tableTestEveryActionHasBeenCalledSuccessfully)outpost_eventsandoutpost_attemptshave not been measured against this criterionRelated
gateway_rename, absorbed into v3.0.0: Outpost support, Gateway MCP write mode, and the gateway_ tool rename #348