# How to derive MCP tool names and schemas from a semantic model

> Derive MCP tools from entities with the sdkgen go-mcp target, edit descriptions where regeneration keeps them, and diff the tools after a spec change.

Source: https://voxgig.com/howto/derive-tool-schemas-from-a-semantic-model

- Audience: api-producer
- Level: intermediate
- Languages: go
- Verified: 2026-11-20
- Published: 2026-11-20

## Short answer

With the sdkgen go-mcp target, tool names come from the project name and the operation, such as greenhouse_load, and the entity argument's enum comes from the model's entities. Descriptions come from a template in the project's copy of the go-mcp component, not from OpenAPI summaries. Edit that component or the model, never go-mcp/tools.go, and diff tools/list after each regeneration.

---
## You will need

An OpenAPI 3 document, Go 1.25 or a Go that can fetch that toolchain, and Node 22 or later.
Verified 2026-11-20 against Node 22.23.5, Go 1.25.0, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, the Go MCP SDK v1.6.0, openapi-mcp-generator 5.0.1, and `ogen` v1.25.0.
`api.v1.json` describes a Greenhouse API with four plant operations whose ids and summaries were
written by hand, badly, on purpose. `api.v2.json` renames one id and adds two zone operations.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-written tool set](https://github.com/modelcontextprotocol/go-sdk) | A few tools shaped like the agent's tasks, each description written for a model | Every description and schema is yours, and the API's changes reach them only when you notice | The API has more operations than you want to hand-maintain |
| [`ogen`](https://ogen.dev/docs/spec/extensions/) | A typed Go client to wrap in tools you write | No MCP output, and doc comments copied from summaries, so descriptions are still yours | You want tools generated, not wrapped |
| [openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator) | Every endpoint as a tool, with nothing between the document and the tool list | Names copied from operationIds and descriptions from summaries, however they were written | The ids are inconsistent and you cannot fix the document |
| [sdkgen go-mcp target](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | You want one naming scheme across every entity, stable across id changes | One description template for every entity, edited in TypeScript, and endpoints outside the entity shape folded away | Each tool needs its own wording |
| [Speakeasy MCP server](https://www.speakeasy.com/docs/standalone-mcp/customize-tools) | You want per-operation names, descriptions, hints, and scopes set in the document | An account-backed toolchain, and summaries as default descriptions until you override them | You will not maintain an extension per operation |

Voxgig maintains sdkgen, the subject of this page. Its row in the table says when another tool
fits better.

Endpoint mapping keeps everything the document says, including the parts written for a person
reading a reference page. The model-derived set trades that for one name pattern and one voice,
and it says less about each entity than a good summary would. Speakeasy sits between them: endpoint
mapping with a per-operation override.

## Read the tool set the model produces

`build.sh` builds the generated server from each of three runs into `bin/`. `toolset` is a Go MCP
client that starts a server over stdio, as an agent host does, and prints its tools.

```bash
bash build.sh
```

```text output
greenhouse-mcp-v1
greenhouse-mcp-v2
greenhouse-mcp-v2-desc
```

```bash
cd toolset && go run . list v2
```

```text output
4 tools from bin/greenhouse-mcp-v2
  greenhouse_create  entity: plant
    Create a record in Greenhouse. Args: entity, data (the new record's fields). Returns the created record as JSON.
  greenhouse_list  entity: plant | zone
    List records from Greenhouse. Args: entity, query (optional filter map; omit it for the first page). Returns the first page of records as JSON.
  greenhouse_load  entity: plant | zone
    Load one record from Greenhouse. Args: entity, query (match map naming the record, such as {"id":1}). Returns the record as JSON.
  greenhouse_update  entity: plant
    Update a record in Greenhouse. Args: entity, data (the record's id and the fields to change). Returns the updated record as JSON.
```

Three things decide this list. The name is the project name, `greenhouse`, plus the operation. The
`entity` enum holds every entity in `.sdk/model/entity` that has that operation. The description is
a sentence per operation with the name Greenhouse filled in. Nothing from an operationId or
a summary appears, so `fetchPlantById` and "Plant detail" never reach the agent.[^1]

## Compare it with endpoint mapping

openapi-mcp-generator maps each operation to a tool. `endpoint-tools.mjs` calls the parser its
command line uses on both documents.

```bash
node endpoint-tools.mjs
```

```text output
api.v1.json: 4 tools
  getPlants       Retrieve all plants (see the Pagination section of this reference)
  plants_create   Creates a Plant resource. Requires the gardener role.
  fetchPlantById  Plant detail
  UpdatePlant     Partially updates a plant. Deprecated fields are ignored; see Changelog 2.3.
api.v2.json: 6 tools
  removed fetchPlantById
  added   getPlant        Get a plant by its ID
  added   list-zones      Zones (beta)
  added   ZoneGet         Returns a single zone.
```

The six tools use four naming styles, and the rename replaced `fetchPlantById` with another tool. Each description is the summary,
written for a reader who can scroll to the Pagination section. That is the pitfall: summary text is
reference prose, and copied into a tool it tells the agent about pages and roles it cannot see.

## Diff the tool set after the spec change

Regenerate from `api.v2.json` and diff the two servers' `tools/list`.

```bash
cd toolset && go run . diff v1 v2
```

```text output
v1 -> v2
  greenhouse_create  unchanged
  greenhouse_list    entity enum [plant] -> [plant zone]
  greenhouse_load    entity enum [plant] -> [plant zone]
  greenhouse_update  unchanged
```

The renamed operationId changed nothing, because no name comes from it. The two zone operations
widened two enums instead of adding two tools.

## Change a description where regeneration keeps it

The description template is in `.sdk/src/cmp/go-mcp/Main_go-mcp.ts`, the project's copy of the
component that writes `tools.go`. The sample's first attempt edited `go-mcp/tools.go` directly,
kept as `tools.hand-edited.go`, and the next `npm run generate` replaced the file with the
unedited one. The second edit changed line 494 of the component so each description names its
entities.

```ts title="Main_go-mcp.ts"
		Description: ${JSON.stringify(spec.verb + ' ' + model.Name + ' (entity: ' + entityNames(tool).join(' or ') + '). Args: entity, ' + spec.key + ' (' + spec.help + '). Returns ' + spec.returns + ' as JSON.')},
```

```bash
cd toolset && go run . diff v2 v2-desc
```

```text output
v2 -> v2-desc
  greenhouse_create  description
  greenhouse_list    description
  greenhouse_load    description
  greenhouse_update  description
```

A second `npm run generate` kept the edit, and `npx voxgig-sdkgen doctor` reported the file as
`CUSTOMIZED`, which an add merges its updates into. The model holds the other levers: the entity
names, an entity switched off in `.sdk/model/guide/guide.aontu`, and
`main: kit: target: 'go-mcp': tool: write: true`, which this sample sets to get `greenhouse_create`
and `greenhouse_update`.

## Set the descriptions in Speakeasy and the Go client generator

Speakeasy reads the `x-speakeasy-mcp` extension on an operation. Its
[tool customization page](https://www.speakeasy.com/docs/standalone-mcp/customize-tools) lists
`name`, `title`, `description`, `scopes`, `disabled`, and the four hints. The default description
is the operation's summary and description, so the summary pitfall is the default. An overlay can
add the extension without editing the document, which is how the edit survives regeneration.
The server it [generates](https://www.speakeasy.com/docs/standalone-mcp/build-server) is
TypeScript, so a Go shop runs a second runtime for it. Speakeasy was not run here, because its CLI
needs `speakeasy auth login`.

`ogen` has no MCP target. It generates a Go client whose method names follow the operationIds and
whose doc comments copy the summaries.

```bash
sed -n '/^type Invoker interface/,/^}/p' ogen/oas_client_gen.go | grep -E '^	// [A-Z].*\.$'
```

```text output
	// GetPlant invokes getPlant operation.
	// Get a plant by its ID.
	// GetPlants invokes getPlants operation.
	// Retrieve all plants (see the Pagination section of this reference).
	// ListZones invokes list-zones operation.
	// Zones (beta).
	// PlantsCreate invokes plants_create operation.
	// Creates a Plant resource. Requires the gardener role.
	// UpdatePlant invokes UpdatePlant operation.
	// Partially updates a plant. Deprecated fields are ignored; see Changelog 2.3.
	// ZoneGet invokes ZoneGet operation.
	// Returns a single zone.
```

Wrap these methods in tools with the Go MCP SDK and write each description by hand. Its
[extensions page](https://ogen.dev/docs/spec/extensions/) offers `x-ogen-name` for type names and
`x-ogen-operation-group` for server handler groups, and names no extension that renames a client
method.

## Check it worked

Run the fixed task set against both servers. Each task names the tool and arguments that carry it
out and the request the API must receive.

```bash
cd toolset && go run . tasks v1 v2
```

```text output
6 tasks against v1
  show every plant                 greenhouse_list    GET /v1/plants       ok
  read plant p1                    greenhouse_load    GET /v1/plants/p1    ok
  add a basil plant                greenhouse_create  POST /v1/plants      ok
  set plant p1's moisture to 0.4   greenhouse_update  PATCH /v1/plants/p1  ok
  list the zones                   greenhouse_list    entity zone not offered
  read zone z1                     greenhouse_load    entity zone not offered
6 tasks against v2
  show every plant                 greenhouse_list    GET /v1/plants       ok
  read plant p1                    greenhouse_load    GET /v1/plants/p1    ok
  add a basil plant                greenhouse_create  POST /v1/plants      ok
  set plant p1's moisture to 0.4   greenhouse_update  PATCH /v1/plants/p1  ok
  list the zones                   greenhouse_list    GET /v1/zones        ok
  read zone z1                     greenhouse_load    GET /v1/zones/z1     ok
```

The four plant tasks resolve to the same tool and the same request before and after, and the zone
tasks resolve once v2 offers the entity. The Go tests assert the same and more.

```bash
cd toolset && go test -count=1 -v . | grep -o -- '--- PASS: [A-Za-z]*'
```

```text output
--- PASS: TestDescriptionsDoNotCopyTheSummaries
--- PASS: TestSpecChangeKeepsNamesAndDescriptions
--- PASS: TestDescriptionEditLivesInTheComponent
--- PASS: TestFixedTasksStillResolve
```

This task set checks that each task still maps to a tool and a request. It does not measure
whether a model picks that tool, which needs the same prompts run against both tool lists.

## When it goes wrong

The description says nothing about the entity. Every entity shares one template, so
`greenhouse_create` tells the agent it creates "a record in Greenhouse" and leaves the rest to the
enum. Edit the component, as the earlier section does, so the text names what each tool can reach.

A task reports `entity zone not offered`, as both zone tasks do against v1. The enum lists only
the entities in `.sdk/model/entity` that have the operation, so the entity is missing from the
model or switched off in the guide. Read `.sdk/model/entity` after every regeneration.

A hand edit to `tools.go` disappears. Generation rewrites it, as `tools.hand-edited.go` shows.

## When not to do this

Do not use the sdkgen go-mcp target when each tool needs its own wording. One template serves
every entity, and an edit to it changes them all at once. Speakeasy's per-operation
`x-speakeasy-mcp` description suits that case better, if an account-backed toolchain is acceptable.

Do not derive tools from a model when the API is mostly actions. Entity operations fold the
actions away, and `ogen`'s one method per operation keeps each of them under its own name.

Do not copy summaries into descriptions on the strength of a generator's default. Read each one
as an agent would, with no access to the reference page it was written for.

## Related how-tos

- [Choose between one tool per operation and one search tool](/howto/choose-tool-granularity-per-operation-or-search)

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

- [Map one tool definition to MCP, OpenAI, Claude, and Gemini](/howto/convert-tool-definitions-between-mcp-openai-claude-gemini)

- [Design filter and sort arguments for a list tool](/howto/design-filter-and-sort-tool-arguments)

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

## 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, `@voxgig/apidef` 8.32.4, the Go MCP SDK v1.6.0, openapi-mcp-generator
5.0.1, and `ogen` v1.25.0. Every output block is what the command preceding it printed. The sdkgen
runs and the `ogen` run happened once, and their output is committed; the servers are built from it
on each check. Speakeasy was not run. Its options come from its documentation.

[^1]: The [tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
asks for names of 1 to 128 characters drawn from ASCII letters, digits, underscore, hyphen, and dot,
unique within a server. It writes every one of those rules as a SHOULD. `greenhouse_update` uses
17 characters and the underscore. openapi-mcp-generator's `list-zones` uses the hyphen and `ZoneGet`
the capitals, so all eleven names on this page conform, whatever an agent makes of them.