# 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.

Source: https://voxgig.com/howto/choose-tool-granularity-per-operation-or-search

- Audience: api-producer
- Level: advanced
- Languages: go, typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://github.com/niieani/gpt-tokenizer), a stand-in for any one
model's tokenizer. The [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
defines what a server lists.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Cloudflare Code Mode](https://developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-mcp-server/) | Tasks that chain calls, on Cloudflare Workers | An experimental package, plus a sandbox for code the model writes | Tasks are single calls, or model-written code cannot run |
| [Hand-written meta-tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) | Hundreds of operations and a tight token budget per request | Two discovery calls before each new operation, and a guess when the agent skips them | Agents call a few operations often |
| [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen#generating-api-clients) | A Go tool server over typed methods that take a `context.Context` | No tools generated, so every definition and its dispatch is code you keep current | You want the tool list generated with the client |
| [openapi-mcp-generator one tool per endpoint](https://github.com/harsha-iiiv/openapi-mcp-generator) | A few dozen operations, or `x-mcp` filtering keeps the list short | Every listed definition rides on every request: 15,818 tokens here | The API has hundreds of operations |
| [sdkgen go-mcp verb tools](https://github.com/voxgig/sdkgen) | An entity-shaped API, with a Go server generated beside the SDK | An open `data` object with no field schema, and a tool context the calls ignore | The operations are actions rather than entity operations |
| [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/) | Typed clients in several languages, wrapped as tools by hand | No tools generated, and an untagged document puts all 200 operations on one service | You 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:

```bash title="generate.sh"
(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:

```bash
node inventory.mjs
```

```text output
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:

```go title="generated/go-mcp-tools.go"
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:

```bash
cat generated/go-mcp-calls.txt
```

```text output
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:

```ts title="tasks.mjs"
    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:

```bash
node measure.mjs
```

```text output
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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/)
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](https://github.com/oapi-codegen/oapi-codegen#generating-api-clients) 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.

```bash
node --test granularity.test.mjs
```

```text output
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:

```bash
node overlap.mjs
```

```text output
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.

## Related how-tos

- [Name tools so an agent picks the right one from fifty](/howto/name-tools-so-agents-pick-the-right-one)

- [Prune a generated MCP server to ten tools an agent can use](/howto/prune-a-generated-mcp-server-to-ten-tools)

- [Measure the token cost of an agent task against your API](/howto/measure-token-cost-per-agent-task)

- [Generate an MCP server from an OpenAPI document](/howto/generate-an-mcp-server-from-openapi)

- [Choose between calling an SDK directly and using MCP](/howto/direct-sdk-calls-versus-mcp-in-an-agent)

## 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.

[^1]: The [MCP pagination rules](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
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.

[^2]: Cloudflare's [post on Code Mode for MCP](https://blog.cloudflare.com/code-mode-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.