How-to › Use AI to do the integration

How to cut the tool count for an API with hundreds of operations#

Build four smaller tool lists from one 200-operation OpenAPI document, measure the tokens each request carries, and see which wrong arguments each list stops.

Audience
Agent builder
Level
advanced
Topic
Build an agent that calls APIs
Languages
TypeScript and Python
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Anthropic tool search tool with deferred loadingHundreds of tools on the Anthropic API, most unused per taskWorks for Anthropic’s models only, and every definition is still sent in every requestYour agent also calls other providers’ models
@voxgig/apidef entity groupingA resource-shaped API, and tool lists built in your own codeA model step to pin, and the model built here kept none of the document’s enumsThe operations are actions with no entity behind them
Fern toolsets and merged toolsA hosted MCP server, with groups set in configurationA Fern account, and hosted servers billed per tool callYou want to generate the server offline, with no vendor account
orval tag filtersA TypeScript MCP server per tag, generated offlineOne tool per operation inside each server, so each group stays largeGroups need fewer tools than operations
Subagents per tool groupTasks that stay inside one group of the APITwice the requests per task, and routing that the orchestrator can get wrongMost 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.

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

  1. The Anthropic documentation caps deferred tools at 10,000 per request, and lets one search ask for any limit from 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

  2. Merged tools need Fern CLI 5.222.0 or later, according to the configure page. The npm registry dates fern-api 5.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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.