How-to › Expose your API to agents

How to choose between one tool per operation and one search tool#

Run one task set through four tool shapes over a 200-operation API, count calls, tokens, and failures, and keep each operation reachable through one tool only.

Audience
API producer
Level
advanced
Topic
Design tool schemas agents can use
Languages
Go and TypeScript
Verified

Read first: Name tools so an agent picks the right one from fifty

Your API has 200 operations, and the MCP server generated from it lists 200 tools. Every request to the model carries all of them, 15,818 tokens of definitions before any work starts. Replace them with one search tool and the list shrinks to a few hundred tokens, but each call then waits on discovery calls that a hurried agent skips.

What you get

You will end up with four tool shapes over one 200-operation API, measured on five tasks for calls, tokens, and failures. A check fails when one operation is reachable two ways. This is for you if you publish tools for a large API.

Short answer

Run one fixed task set through each tool shape and count calls, tokens, and failed calls before you choose. Over 200 operations, one tool per endpoint costs 15,818 tokens per request. sdkgen’s go-mcp target lists five verb tools for 1,388. Three meta-tools cost 160 but take more than twice the calls, and fail when the schema call is skipped. Then keep each operation reachable through exactly one tool.

You will need

Node 22 or later, an OpenAPI 3 document for an API with many operations, and an MCP server or a plan for one. Verified 2026-11-20 against Node 22.23.5. The document here is a Fleet API with 40 resources and five operations each, written by make-api.mjs. Token counts use the o200k encoding of gpt-tokenizer, a stand-in for any one model’s tokenizer. The MCP tools specification defines what a server lists.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Cloudflare Code ModeTasks that chain calls, on Cloudflare WorkersAn experimental package, plus a sandbox for code the model writesTasks are single calls, or model-written code cannot run
Hand-written meta-toolsHundreds of operations and a tight token budget per requestTwo discovery calls before each new operation, and a guess when the agent skips themAgents call a few operations often
oapi-codegenA Go tool server over typed methods that take a context.ContextNo tools generated, so every definition and its dispatch is code you keep currentYou want the tool list generated with the client
openapi-mcp-generator one tool per endpointA few dozen operations, or x-mcp filtering keeps the list shortEvery listed definition rides on every request: 15,818 tokens hereThe API has hundreds of operations
sdkgen go-mcp verb toolsAn entity-shaped API, with a Go server generated beside the SDKAn open data object with no field schema, and a tool context the calls ignoreThe operations are actions rather than entity operations
Swagger CodegenTyped clients in several languages, wrapped as tools by handNo tools generated, and an untagged document puts all 200 operations on one serviceYou want the tool list generated with the client

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

The shapes trade the cost of a request against the cost of a task. One tool per endpoint is precise per call and pays for 200 definitions every turn. The meta-tools are nearly free to list and spend extra round trips on discovery. Code Mode collapses a task into one call, at the price of running code the model wrote. The two client generators leave the choice, and the dispatch, to you.

Count what each generator made of 200 operations

generate.sh ran each generator once on api.json and kept what the page reads under generated/. The sdkgen run asks its go-mcp target for the write tools, which are off by default:

(cd work && npx --yes @voxgig/create-sdkgen@0.31.9 fleet --def ../api.json -t go -t go-mcp)
printf "\n# Generate the write tools too (off by default).\nmain: kit: target: 'go-mcp': tool: write: true\n" \
  >> work/fleet-sdk/.sdk/model/project.aontu
(cd work/fleet-sdk/.sdk && npm run generate)
(cd work/fleet-sdk/go-mcp && go build -o ../../fleet-mcp .)

Count the results:

node inventory.mjs
Swagger Codegen 3.0.85, -l go: 200 methods on DefaultApiService
  GetVehicle(ctx context.Context, vehicleId string) (Vehicle, *http.Response, error)
oapi-codegen v2.8.2: 280 methods on ClientInterface, 80 of them ...WithBody
  GetVehicle(ctx context.Context, vehicleId string, reqEditors ...RequestEditorFn) (*http.Response, error)
openapi-mcp-generator 5.0.1: 200 tools
sdkgen go-mcp: 5 tools, 40 entities in each one's enum
  fleet_create, fleet_list, fleet_load, fleet_remove, fleet_update

Both servers answered tools/list in one page.1 The go-mcp target does not emit one tool per entity operation. It emits one tool per verb and takes the entity as an enum argument, so the list stays at five whether the API has four entities or forty. Each call goes through one dispatch function:

func runOp(_ context.Context, client *sdk.FleetSDK, op string, entity string, input map[string]any) (*mcp.CallToolResult, any, error) {
	ent, err := entityFor(client, entity)
	if err != nil {
		return toolError(err.Error())
	}

	var result any
	switch op {
	case "list":
		result, err = ent.List(input, nil)
	case "load":
		result, err = ent.Load(input, nil)

The context arrives as _ and goes no further, so a client that cancels a tool call does not cancel the HTTP request behind it. The binary was built and called once, against a stand-in:

cat generated/go-mcp-calls.txt
fleet_load {"entity":"vehicle","query":{"id":"v-17"}}
  { "id": "v-17", "name": "Van 17" }
fleet_list {"entity":"vehicle"}
  [ { "id": "v-17", "name": "Van 17" } ]
fleet_create {"entity":"vehicle","data":{"name":"Van 18"}}
  { "id": "v-17", "name": "Van 17" }
fleet_update {"entity":"vehicle","data":{"id":"v-17","status":"parked"}}
  { "id": "v-17", "name": "Van 17" }
fleet_remove {"entity":"vehicle","query":{"id":"v-17"}}
  { "id": "v-17", "name": "Van 17" }
fleet_load {"entity":"vehicle","query":{"vehicleId":"v-17"}}
  isError FleetSDK: load: URL path has no value for {id}.
requests the stand-in received:
  GET /vehicles/v-17
  GET /vehicles
  POST /vehicles {"name":"Van 18"}
  PATCH /vehicles/v-17 {"id":"v-17","status":"parked"}
  DELETE /vehicles/v-17

The record is named by id, whatever the document calls its path parameter, and a wrong key comes back as a tool error the agent can read.

Run the same five tasks through every shape

tasks.mjs holds five tasks: a read, a create, a delete, a rename, and one that lists faults and closes the open ones at one site. Each shape gets a scripted policy in place of a model, and each task runs against a fresh in-memory copy of the API, which then checks the outcome. The third task, as the step-by-step policies and the code tool see it:

    name: 'close every open fault at site cork',
    run: async (step) => {
      const open = (await step('listFaults')).filter((f) => f.site === 'cork' && f.status === 'open')
      for (const f of open) await step('updateFault', { faultId: f.id }, { status: 'closed' })
      return open.map((f) => f.id)
    },
    code: [
      "const open = (await api.listFaults()).filter((f) => f.site === 'cork' && f.status === 'open')",
      "for (const f of open) await api.updateFault({ faultId: f.id, body: { status: 'closed' } })",
      'return open.map((f) => f.id)',
    ].join('\n'),

The code tool here is a stand-in in the shape the Code Mode documentation describes, a declaration of every operation in one tool’s description. It is not Cloudflare’s code. A task’s requests are its tool calls plus one for the final answer:

node measure.mjs
task set: 5 tasks, o200k tokens
shape                        tools  per request  calls  failed  correct  definition tokens  result tokens
one tool per endpoint          200        15818      8       0      5/5             205634            405
one tool per verb (go-mcp)       5         1388      8       0      5/5              18044            405
three meta-tools                 3          160     20       0      5/5               4000           1375
meta-tools, schema skipped       3          160     22       4      4/5               4320           1333
one code tool                    1         4229      5       0      5/5              42290             76

Read the definition column first, because it repeats on every turn of every conversation. Two hundred tools cost about eleven times the five verb tools, for the same eight calls.2 The meta-tools cut the list to 160 tokens and take 20 calls, because each new operation costs a search and a schema read first. The code tool ran each task in one call, and only the code’s return value came back.

The fourth row measures the usual failure of meta-tools. A policy that searches and then invokes with guessed argument names fails four calls, recovers from each, and still gets one task wrong. The guessed create passed name and site at the top level, where the tool reads only requestBody, so the API stored an empty ticket and reported success.

Selection accuracy is not in the table. A scripted policy never picks the wrong tool, so that column needs a real model behind measure, run on the same five tasks and judged by the same checks.

Wrap a Swagger Codegen or oapi-codegen client in tools

Neither generator writes MCP tools, so with either one the shape is yours to build. The Swagger Codegen v3 documentation lists client, server stub and documentation generators but no tool generator. Its Go client put all 200 operations on one DefaultApiService, because the document tags none of them. Each method takes a context and returns a typed model, so one tool per method is a short loop of definitions. A verb or meta-tool shape needs a dispatch table from tool arguments to methods, written by hand.

oapi-codegen generates Go types and a client, and its README names no tool or MCP output. Its ClientInterface carries 280 methods: one per operation, plus a WithBody variant for each of the 80 operations with a request body. Every method takes a context.Context and RequestEditorFn callbacks, so a dispatch layer you write can pass cancellation and credentials through. With both generators, the per-verb or meta shape from catalogs.mjs is the part you would port to Go.

Check it worked

Eleven tests pin the measurement. They match the 200 operationIds to the 200 tools and check the five verb tools and their 40-entity enums. They pin the order of per-request costs, the meta-tools’ extra calls, and the four failures and empty write when the schema is skipped. One checks that this page’s per-verb dispatch sends the requests the real binary sent.

node --test granularity.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 301.904722

When it goes wrong

The agent updates a vehicle through one tool and reads it back through another. Someone added per-endpoint vehicle tools beside the five verb tools, so each vehicle operation is reachable two ways, with two argument conventions. An approval rule or an audit filter written against one tool name misses the other. overlap.mjs lists every operation more than one tool reaches:

node overlap.mjs
go-mcp tools alone: 5 tools, 0 operations reachable two ways
go-mcp tools plus five vehicle tools: 10 tools, 5 operations reachable two ways
  createVehicle   fleet_create, createVehicle
  listVehicles    fleet_list, listVehicles
  getVehicle      fleet_load, getVehicle
  deleteVehicle   fleet_remove, deleteVehicle
  updateVehicle   fleet_update, updateVehicle
fleet_load {entity, query.id} and getVehicle {vehicleId} both sent: GET /vehicles/v-17, GET /vehicles/v-17

In CI, assert that overlaps() returns nothing for the catalog you ship, as the test does, and pick one shape per server.

The verb tools write a field the API does not have. fleet_create takes data as an open object, so the schema cannot tell an agent the record’s field names. Put the field list in the description, or keep per-endpoint tools for the few writes where shape matters.

fleet_load answers URL path has no value for {id}. The agent named the record with the document’s path parameter, vehicleId, but the verb tools read id from query. Send query: { id }, the form the tool’s own description gives as its example.

When not to do this

Do not mix tool shapes in one server. An operation reachable through two tools splits every rule keyed on a tool name, and the measurement on this page cannot see which route an agent will take.

Do not pick sdkgen’s go-mcp verb tools for an API whose operations are actions. Five verbs over an entity enum describe a CRUD API well, but an endpoint such as a refund or a dispatch has no verb to sit under. Its tools also drop the call’s context, so cancellation stops at the server.

Do not ship meta-tools to agents that call the same handful of operations all day. They pay two discovery calls per operation per conversation, which a short list of named tools avoids.

Choose oapi-codegen for a Go tool server where each tool must honor cancellation and pass per-request credentials, since every method takes a context and request editors. Choose Swagger Codegen when the tools wrap clients in several languages and each needs a typed method per operation.

Last verified

Verified 2026-11-20 against Node 22.23.5, Go 1.25.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, openapi-mcp-generator 5.0.1, Swagger Codegen 3.0.85, oapi-codegen v2.8.2 and gpt-tokenizer 4.1.2. Every output block is what the command preceding it printed. Each generator ran once in generate.sh, and its output is committed under generated/. The go-mcp binary and the openapi-mcp-generator server were started to list their tools and are not re-run on each build. Cloudflare Code Mode was not run; its shape comes from its documentation.

Footnotes

  1. The MCP pagination rules let a server split a long tools/list into pages, with the page size set by the server and a cursor to ask for the next one. Neither server here used them. The per-endpoint server sent all 200 definitions in its first and only page, which is the whole tool list a client will forward. ↩︎ Back to text

  2. Cloudflare’s post on Code Mode for MCP starts from a larger catalog. Its summary says the Cloudflare API has over 2,500 endpoints, that one MCP tool each would consume over two million tokens, and that two tools and roughly 1,000 tokens replaced them. The body of the same post gives a lower figure for that server, 1.17 million tokens measured with tiktoken, which comes to about 470 an endpoint. The Fleet document here averages 79 a tool, with four fields in each schema. ↩︎ 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.