Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 16 of 16

OpenAPI tool generation

0 of 16 complete

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

Describe, validate, call, translateInteractive

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

Step 1/5 · describe
describe · operationcall · Host → Host
{ "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.

  1. Select the operations that correspond to user intents, and exclude admin, bulk and internal endpoints.
  2. Require an operationId and a description with purpose, preconditions and what the response contains.
  3. Flatten request schemas, resolve references, and replace oneOf or anyOf with a discriminator the model can follow.
  4. Map HTTP errors to a small set of codes and keep the upstream message out of the model's context unless it is actionable.
  5. Inject authentication at the HTTP client, scoped to the caller, and never expose the token as a tool parameter.
  6. Regenerate on spec change and diff the tool list, because a new endpoint appears without a code review.

Trade-offs

ChoiceGood forCostFails when
Generate from the full specComplete coverageHundreds of ambiguous toolsThe API has more than a few dozen operations
Curated subsetGood selection accuracyManual curation and driftThe API changes frequently
Hand-written wrappersBest descriptions and shapingMaintenance cost per endpointThe API is large and stable
Generic request toolOne tool for everythingNo schema guidance and wide authorityThe model must construct URLs and bodies
Trade-off mapInteractive

Good for

Complete coverage

Cost

Hundreds of ambiguous tools

Fails when

The API has more than a few dozen operations

  1. The API has more than a few dozen operations
  2. The API changes frequently
  3. The API is large and stable
  4. 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