Your agent calls an API with 200 operations, so every request it sends to the model carries 200 tool definitions. Here that is 10,339 tokens before the user’s message. The list travels again on every turn, and the model has to pick one tool out of all of them each time, including on turns that need none.
What you get
You will end up with four smaller tool lists built from one OpenAPI document, each measured in tokens per request and checked against wrong arguments. This is for you if your agent loads tools for a large API and you decide what it loads.
Short answer
Build a smaller tool list from the same document and measure tokens per request before you pick
one. @voxgig/apidef sorts 200 operations onto 36 entities, and one tool per entity with an
action argument cuts the definitions in each request from 10,339 o200k tokens to 4,338. A keyword
filter sends five tools per request, and subagents see six each. On the Anthropic API, defer the
operation tools behind the tool search tool, and never defer every tool.
You will need
Node 22 or later, an OpenAPI 3 document with many operations, and an agent loop whose tool list
you control. The document here is a Store API with 36 resources in six tags and 20 action
endpoints, written by make-api.mjs. Every token count on the page is an o200k count of the
tools array as JSON, made with gpt-tokenizer. Another
model’s tokenizer gives other numbers, so read each count as an estimate and compare the ratios.
How many tools the server should expose in the first place is a separate decision,
made in Choose between one tool per operation and one search tool.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Anthropic tool search tool with deferred loading | Hundreds of tools on the Anthropic API, most unused per task | Works for Anthropic’s models only, and every definition is still sent in every request | Your agent also calls other providers’ models |
| @voxgig/apidef entity grouping | A resource-shaped API, and tool lists built in your own code | A model step to pin, and the model built here kept none of the document’s enums | The operations are actions with no entity behind them |
| Fern toolsets and merged tools | A hosted MCP server, with groups set in configuration | A Fern account, and hosted servers billed per tool call | You want to generate the server offline, with no vendor account |
| orval tag filters | A TypeScript MCP server per tag, generated offline | One tool per operation inside each server, so each group stays large | Groups need fewer tools than operations |
| Subagents per tool group | Tasks that stay inside one group of the API | Twice the requests per task, and routing that the orchestrator can get wrong | Most tasks cross groups |
Voxgig maintains apidef. It is one of five options here, not the recommendation.
The options split on where the cut happens. Deferred loading keeps the full list and lets the provider hide most of it, which ties you to one API. Grouping and filtering shrink what you send, at the price of schemas that know less about each call. Subagents keep each list small and double the round trips, and Fern and orval move the grouping into the generated server.
Group the operations by entity with apidef
model.mjs calls ApiDef.makeBuild with generation switched off, on the release pinned in
package-lock.json, and prints what the model made of the document:
node model.mjs api.json
apidef 8.32.4: 200 operations on 36 entities, 0 warnings
by slot: create 56, list 36, load 36, remove 36, update 36
20 of the create points carry an $action
order: create/$action=cancel, create/$action=fulfil, create, list, load, remove, update
same as generated/model-8.32.4.json: yes
Every operation landed on an entity. The 20 action endpoints, such as
POST /orders/{orderId}/cancel, became extra points of create with an $action selector,
which the model reference
describes. generate.sh also built the document on apidef 8.33.1 and compared the two with
compare-releases.mjs. The part the tools read came out the same. The whole model differs in
12 values: 8.32.4 names the {taxId} parameter tax_id, where the other 35 entities get id,
and 8.33.1 names it id. Pin the release that built your tools.
One tool per entity follows from that shape. The action list comes from the slots and the
$action values:
// Shape 2: one tool per apidef entity, with an action argument.
export function perEntity(kit = model) {
return Object.entries(kit.entity).map(([name, entity]) => {
const actions = actionsOf(entity).map((a) => a.action)
const data = {}
for (const f of entity.fields) if (f.n !== 'id') data[f.n] = { type: 'string' }
return {
name,
description: `Act on ${name} records. action is one of ${actions.join(', ')}.`,
input_schema: {
type: 'object',
properties: {
action: { type: 'string', enum: actions },
id: { type: 'string', description: `The ${name} id, for actions on one record` },
data: { type: 'object', properties: data, additionalProperties: false },
},
required: ['action'],
additionalProperties: false,
},
}
})
}
dispatch in the same file routes a call back to its method and path. It checks what one shared
schema cannot: an id for the actions on one record, and the fields the model marks required.
Measure what each list costs per request
Nine tasks, each needing one operation, run through four lists. The filter scores every definition against the user’s message and sends the best five, which is what a client does by hand on a provider without server-side search. A subagent task takes four requests: the orchestrator delegates, the subagent calls and answers, and the orchestrator answers.
node measure.mjs
9 tasks over 200 operations and 36 apidef entities, o200k tokens
tactic most tools largest request requests tokens, all tasks tool in list
per operation 200 10339 18 186102 9/9
per entity (apidef) 36 4338 18 78084 9/9
filtered per request 5 305 18 4458 9/9
subagent per group 6 731 36 18994 9/9
filter: the needed tool ranked 5th at worst, and scored highest on its own in 4 of 9 tasks (cancelOrder, createVoucher, closeTicket, listShipments)
filter: a tool with the needed tool's score was left out of the five in 0 of 9 tasks
deferred loading still sends all 200 definitions: 46724 bytes in every request
The filter is the cheapest list here, and the needed tool was in its five for all nine tasks. Only four messages scored it higher than every other tool. The other five named the entity but not the verb, so the filter sent operations on that entity in document order, with the needed one as low as fifth.
The subagents cost about four times the filter but keep a whole group in view. The 36 entity tools cost less than half of the per-operation list over the nine tasks, and four times the subagents.
The last column counts a tool in the list, not a correct call. It is a check that the needed tool was offered, never a measure of what a model would do with it, and the subagent row assumes the orchestrator picked the right group. No model was called to test either.
Defer the tools on the Anthropic API
The tool search tool
keeps your list whole. You add tool_search_tool_regex_20251119 or
tool_search_tool_bm25_20251119, set defer_loading: true on the tools that should wait, and the
API loads a deferred tool into context only when a search returns it.1 The documentation is
explicit that every definition is still sent, which is the 46,724 bytes in the last line of the
measurement. deferred.mjs builds that list and refuses the two shapes the documentation forbids:
node deferred.mjs
search tool loaded, 200 deferred: send 201, loaded up front: tool_search_tool_regex
search tool loaded, 3 kept, 197 deferred: send 201, loaded up front: tool_search_tool_regex, getProduct, listOrders, getOrder
search tool deferred, 3 kept: refused, the tool search tool itself is deferred
search tool deferred too: refused, every tool is deferred, so nothing is loaded to search from
The documentation recommends keeping three to five frequent tools loaded, as the second line does. It also gives the 400 the API returns for the last list: “At least one tool must have defer_loading=false. All tools cannot be deferred.” The keyword filter needs no provider feature. Run before each request, it is the same idea done by hand, on any API.
Split the list in Fern and orval
Fern’s MCP Generator turns each operation into one tool, and its
sdk-config.yml settings
shrink the list in three ways. tools takes include and exclude entries, including
tag:<name>. Fern also creates a toolset for each tag and each service with at least two tools,
each at its own URL, so an agent connected to one sees only its tools. mergedTools combines
operations into one tool chosen by a dispatchOn argument, with x-fern-mcp-dispatch-value on
each member. That is this page’s entity grouping, written by hand in configuration.2
The quickstart lists a
Fern account as a prerequisite. It deploys a hosted server, which is
priced by tool calls, or
writes a zip target to run on your own machine, with each toolset at /mcp/<toolset>.
orval writes an MCP server with client: 'mcp', and
input.filters.tags limits it to the
operations under some tags. generate.sh ran orval.config.mjs once over the whole document and
once per tag:
cat generated/orval-tools.txt
orval 8.48.0
all 200
billing 34
catalog 32
logistics 34
orders 35
people 32
support 33
Each tag server is one subagent’s list, and inside it every operation stays its own tool:
tools.cancelOrder = server.registerTool(
'cancelOrder',
{
title: 'Cancel an order',
description: 'Cancel an order',
inputSchema: CancelOrderInput,
outputSchema: CancelOrderResponse,
annotations: { destructiveHint: true },
},
Check it worked
Fifteen tests pin the claims. The pinned apidef rebuilds the committed model, every operation lands on exactly one entity action, and the token counts keep their order. The deferral check refuses every broken list, and orval’s six tag servers add up to the 200 operations.
node --test toolcount.test.mjs
1..15
# tests 15
# suites 0
# pass 15
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1705.913452
When it goes wrong
The request fails with a 400 before the model sees it. Every tool, the search tool included,
carries defer_loading: true, so nothing is loaded to search from. Remove the flag from the
search tool, and run a check such as checkDeferred before the request leaves.
The grouped tool sends a value the API refuses. The one schema per entity built here marks no
per-action required fields, and the apidef model keeps no enum, so the draft, active and
closed values of status are gone. dispatchChecked validates data against the request schema
the document gives the operation. Three wrong calls, checked against both lists and against it:
node args.mjs
load with no id
per operation: schema refuses: $.productId is required
per entity: schema accepts, dispatch refuses: product.load needs an id
per entity, doc schema: schema accepts, dispatch refuses: product.load needs an id
create with a status the API does not have
per operation: schema refuses: $.status is not one of draft, active, closed
per entity: schema and dispatch accept, sent as POST /vouchers
per entity, doc schema: schema accepts, dispatch refuses: $.data.status is not one of draft, active, closed
create with no status
per operation: schema refuses: $.status is required
per entity: schema accepts, dispatch refuses: voucher.create needs data.status
per entity, doc schema: schema accepts, dispatch refuses: voucher.create needs data.status
Validate every call against the document’s schema inside the tool, as the last line of each case does, and return the refusal to the model as the tool’s result.
The filter sends an empty list. It scores words, so a message that shares none with any name, summary or argument matches nothing, and the model gets no tool to call. Fall back to the entity tools when the filter returns nothing, rather than sending the request without tools.
When not to do this
Do not cut a short list. Anthropic’s tool search documentation calls standard tool calling the better fit below ten tools, and every cut on this page costs argument checks or requests.
Do not build tools from the apidef model alone when the document’s enums or formats carry meaning. The model keeps each field’s name, type and required flag but drops this document’s enum values, so check every call against the document before an agent writes through those tools.
Do not defer every tool. Keep the search tool loaded, plus the few tools nearly every task calls.
Fern is the better fit when you want the grouping in configuration and a hosted URL per group, and you accept an account and per-call pricing. orval suits a TypeScript team that wants a server per tag generated offline, with typed Zod input schemas, and can live with one tool per operation inside each group.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/apidef 8.32.4 and 8.33.1, orval 8.48.0 and
gpt-tokenizer 4.1.2. Every output block is what its command printed. The test rebuilds
the model with apidef, and generate.sh ran orval and apidef 8.33.1 once and committed
their output. No model was called, so neither Anthropic’s tool search nor any task success
rate was measured. Fern was not run, and everything said of it comes from its MCP Generator
documentation.
Footnotes
-
The Anthropic documentation caps deferred tools at 10,000 per request, and lets one search ask for any
limitfrom 1 to 10,000, against a default of five. A single search may therefore, in the limits it publishes, return the entire catalog that deferral was set up to keep out of context. ↩︎ Back to text -
Merged tools need Fern CLI 5.222.0 or later, according to the configure page. The npm registry dates
fern-api5.0.0 to April 29, 2026 and 5.222.0 to November 17, 2026. The feature therefore shipped under a minor version number of 222, in a major version first published less than seven months before. ↩︎ Back to text