OpenAPI for Agents

OpenAPI (formerly Swagger) is the OG description language for REST APIs. The latest revisions (3.1.x and 3.2.x) align JSON Schema with the most recent draft, which makes OpenAPI documents a perfect source for LLM tool definitions: same JSON Schema, same descriptions, same field nullability.

The pattern that has emerged: write the OpenAPI document for your service. Generate two artifacts from it — a normal client SDK for human-coded callers, and a tool-list bundle for LLM consumers (function-call definitions, MCP server tools, or both). One source of truth for the contract; many surfaces for the contract's consumers.

Watch for two real differences between human and LLM consumption:

Description quality. Humans tolerate "string, optional" as a parameter description; LLMs select tools by reading those descriptions. Re-read every parameter description in your OpenAPI doc with "would an LLM pick this correctly?" in mind.
Operation grouping. Humans navigate paths and tags; LLMs see a flat tool list. Group related operations into one tool when reasonable, expose distinct semantics as distinct tools, and watch the explosion if you naively map every operation to a separate tool.

Code

Generating LLM tool definitions from OpenAPI·python

# Pseudocode — the spec is enough to drive a transformer
import yaml

oas = yaml.safe_load(open("openapi.yaml"))
tools = []
for path, methods in oas["paths"].items():
    for method, op in methods.items():
        if not op.get("operationId"):
            continue
        tools.append({
            "name": op["operationId"],
            "description": op.get("summary", "") + "\n" + op.get("description", ""),
            "parameters": build_schema_from_oas(op),
        })

Webhooks in OpenAPI 3.1+ — async events as part of the contract·yaml

webhooks:
  orderShipped:
    post:
      summary: Sent when an order is shipped.
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OrderShipped'}

Exercise

Take an OpenAPI document for a service you maintain (or any popular public one) and generate a tool list from it programmatically. Pick three tools and rewrite their descriptions for LLM consumption. The diff between auto-generated and rewritten descriptions is exactly the editorial work that turns a doc into a tool list.

Code

External links

Exercise

Progress

Comments 0