Why it matters
An organisation already has APIs described in OpenAPI, and wrapping each endpoint by hand is tedious. Generation promises coverage in an afternoon. The difficulty is that an OpenAPI document describes HTTP semantics for developers, not intent for a model: hundreds of operations, terse summaries, nested schemas and error formats that vary per endpoint. Generation works when the spec is curated and fails when it is treated as a complete tool catalogue.
Mental model
Generation is a translation machine: it converts a service manual into instructions for a new operator. The metaphor breaks because the manual assumes the reader already knows the domain, and the operator will follow a badly translated step without asking for clarification.
How it works
The failure path is the point: the schema came from API spec v1.8, the API serves v1.9, and only the translation step can keep that drift away from the model.
Host
model + policy
Tool
generated wrapper
API
upstream v1.9
{ "name": "issues_search",
"operationId": "issues_search",
"description": "Find issues by free-text query. Returns id, title and state. Use issues_get for full text.",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" },
"state": { "type": "string",
"enum": ["open", "closed", "any"] } },
"required": ["query"] } }
Generated from API spec v1.8 in an OpenAPI 3.1
document. The description states purpose and
limits, not a one-line summary.Step 1: describe. Hover, tap or tab to any message to inspect its payload.
Figure. A generated tool is four checkpoints — describe, validate-and-correct, call, translate — with validation and correction split into two player steps. Here local validation passes and the API still rejects, because the tool was generated from an older API spec.
What to notice. The failure is a 4xx treated as transient. 422 means the request was understood and refused — retrying sends the same rejected call, and the model needs the field, not the raw body. A 5xx is the retryable case, with backoff and an idempotency key on writes; the second failure is auth in the schema, where an API key becomes a tool argument the model can fill or leak.
Text version
Sequence across Host, Tool and API. Step 1, describe: a self-message on Host lists the generated descriptor for issues_search, with operationId, a description and a flattened input schema for query and state, generated from API spec v1.8 in an OpenAPI 3.1 document. Step 2, validate: Host to Tool invoke with query upload timeout and state opened; Tool to Host a schema violation because state must be open, closed or any, rejected before HTTP. Step 3, correct: Host to Tool invoke with state open. Step 4, call: Tool to API GET /issues?state=open with a bearer token injected by the HTTP client, not present in the tool schema; API to Tool 422 unknown query parameter state. Step 5, handle: Tool to Host a mapped error with status 422, retryable false and field state; a self-message on Host records the policy: other 4xx not retried, 401 re-authenticate, 403 forbidden and not retried, 408 retry with backoff, 429 honour Retry-After, 5xx retry with backoff, and POST retries need an idempotency key. The generated tool came from API spec v1.8 while the API serves v1.9.
- Select the operations that correspond to user intents, and exclude admin, bulk and internal endpoints.
- Require an operationId and a description with purpose, preconditions and what the response contains.
- Flatten request schemas, resolve references, and replace oneOf or anyOf with a discriminator the model can follow.
- Map HTTP errors to a small set of codes and keep the upstream message out of the model's context unless it is actionable.
- Inject authentication at the HTTP client, scoped to the caller, and never expose the token as a tool parameter.
- Regenerate on spec change and diff the tool list, because a new endpoint appears without a code review.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Generate from the full spec | Complete coverage | Hundreds of ambiguous tools | The API has more than a few dozen operations |
| Curated subset | Good selection accuracy | Manual curation and drift | The API changes frequently |
| Hand-written wrappers | Best descriptions and shaping | Maintenance cost per endpoint | The API is large and stable |
| Generic request tool | One tool for everything | No schema guidance and wide authority | The model must construct URLs and bodies |
Good for
Complete coverage
Cost
Hundreds of ambiguous tools
Fails when
The API has more than a few dozen operations
- The API has more than a few dozen operations
- The API changes frequently
- The API is large and stable
- The model must construct URLs and bodies
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Generate from the full spec is good for Complete coverage, costs Hundreds of ambiguous tools, and fails when The API has more than a few dozen operations. Curated subset is good for Good selection accuracy, costs Manual curation and drift, and fails when The API changes frequently. Hand-written wrappers is good for Best descriptions and shaping, costs Maintenance cost per endpoint, and fails when The API is large and stable. Generic request tool is good for One tool for everything, costs No schema guidance and wide authority, and fails when The model must construct URLs and bodies
Failure modes
- Tool explosion. Every endpoint becomes a tool and selection accuracy collapses. Debug: count tools exposed and measure selection on a labelled query set before and after generation.
- Description as a summary field. The spec's one-line summary is used as the tool description and the model cannot tell similar operations apart. Debug: list tools whose descriptions are under a few words and review them.
- Auth in the schema. An API key parameter is generated as a tool argument and the model fills it or leaks it. Debug: inspect the generated schema for credential fields and remove them.
In production
Monitor tool count per API and selection accuracy after each regeneration. Treat a spec change as a prompt change and review the generated diff before deployment.
Common misconceptions
People think: A good OpenAPI spec is a good tool definition.
Actually: It describes HTTP for developers; tool definitions need intent, selection guidance and model-sized schemas.
People think: Generation removes maintenance.
Actually: It moves maintenance into the spec and the curation list, which still need review.
Interview angle
A strong answer starts from operation selection and description quality, then covers schema flattening and auth. It also names the tool-count limit. Weak answers say to point a generator at the spec.
Sources
- OpenAPI Specification 3.1 — operations, operationId and schema composition.
- Patil et al., Gorilla — matching a request to an API operation at scale.
- OpenAI, Function calling guide — the tool schema format the generated output targets.