Your generated MCP server names its tools getPlants, plants_create, and UpdatePlant, because
three teams wrote the operationIds. One description reads “Plant detail” and another sends the agent
to a Pagination section on a reference page it cannot open. A rename in the spec
then removes a tool that agents were already calling.
What you get
You will end up with a tool set derived from entities and operations and a description change that survives regeneration. A fixed task set confirms that a spec change kept every tool usable. This is for you if agents call tools generated from your API.
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 | 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 | 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 | 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 | 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 | 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 build.sh
greenhouse-mcp-v1
greenhouse-mcp-v2
greenhouse-mcp-v2-desc
cd toolset && go run . list v2
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.
node endpoint-tools.mjs
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.
cd toolset && go run . diff v1 v2
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.
Description: ${JSON.stringify(spec.verb + ' ' + model.Name + ' (entity: ' + entityNames(tool).join(' or ') + '). Args: entity, ' + spec.key + ' (' + spec.help + '). Returns ' + spec.returns + ' as JSON.')},
cd toolset && go run . diff v2 v2-desc
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 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 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.
sed -n '/^type Invoker interface/,/^}/p' ogen/oas_client_gen.go | grep -E '^ // [A-Z].*\.$'
// 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 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.
cd toolset && go run . tasks v1 v2
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.
cd toolset && go test -count=1 -v . | grep -o -- '--- PASS: [A-Za-z]*'
--- 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
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.
Footnotes
-
The tools specification 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_updateuses 17 characters and the underscore. openapi-mcp-generator’slist-zonesuses the hyphen andZoneGetthe capitals, so all eleven names on this page conform, whatever an agent makes of them. ↩︎ Back to text