# Writing one OpenAPI spec that serves both humans and agents

> After building more than 50 MCP servers from OpenAPI, Speakeasy found models got lost choosing among 200 tools; people and agents need different things from a spec.

Original: https://fdetimes.net/en/tools/openapi-swagger-stoplight-readme-llm-spec/

Georges Haidar of Speakeasy drew one lesson after his team built more than 50 production MCP servers from OpenAPI files: when a model has to choose between 200 tools, it gets confused because its context window is overloaded. That observation captures both the strength and the pitfall of today's most widely used API description standard.

The strength is that one spec file can now serve two kinds of reader. The customer's integration team reads it through a docs site; an agent reads it as a list of tools. The pitfall is that those two readers need different things.

If you want to work as an FDE, treat this as a skill you should already have. When a customer asks how your system connects to their ERP, or wants an agent to call an internal API, a clean spec is the first thing to put on the table.

## OpenAPI is the standard, Swagger is the tooling

Many developers still use the two names interchangeably, and history explains why. Swagger began with Tony Tam at Wordnik in 2009. In December 2015 SmartBear handed the specification to an open governance group under the Linux Foundation, and OpenAPI 2.0 is identical to Swagger 2.0.

Since then, OpenAPI has been the standard maintained by the OpenAPI Initiative. The specification describes HTTP APIs independently of any programming language, and the latest version on the official site is 3.2.1. Swagger is SmartBear's toolset built around that standard.

Its open-source suite includes Editor, for writing specs in the browser; UI, for viewing and trying out an API; and Codegen, for generating client libraries, server stubs and documentation.

Stoplight is a platform geared towards design-first work, meaning the spec is written before the code, and it now also belongs to SmartBear following an acquisition. Redoc is another open-source tool, dedicated to generating documentation from a spec, with support for OpenAPI 3.1, 3.0 and Swagger 2.0.

When a job description mentions "Swagger" or "OpenAPI", read it as asking for the same skill: describing an API so that machines can read it.

## One spec, five steps

Picture a logistics company whose IT team needs to integrate with the order-lookup service you are building. The backend is not finished, but both sides need to agree now on what requests and responses look like. Step one is writing the spec; a minimal version for one endpoint might look like this:

```yaml
openapi: 3.1.0
info:
  title: Order Status API
  version: 0.1.0
paths:
  /orders/{order_id}:
    get:
      operationId: getOrderStatus
      summary: Get the status of an order
      description: >
        Use when the user asks where a specific order is.
        Requires order_id as a string; do not use to list multiple orders.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Current status of the order
```

(The summary reads "Get the status of one order". The description says: "Use when the user asks where a specific order is. Requires order_id as a string; do not use to list multiple orders.")

Step two is running Spectral, Stoplight's open-source JSON/YAML linter, to enforce a style guide automatically. Spectral supports OpenAPI 2 through 3.1, as well as Arazzo and AsyncAPI, so you can wire it into CI and stop anyone merging a spec that lacks an `operationId` or a description.

Step three is Prism, also from Stoplight, which turns an OpenAPI file or a Postman Collection into a mock server with validation. The customer's IT team can start calling it today, and sending the wrong data type returns an error, while the real backend is still being written. This is usually the fastest way to surface misunderstandings about the schema before they become bugs at go-live.

Step four is documentation: Swagger UI or Redoc builds the docs site from that same file, and Swagger Codegen generates SDKs if the customer wants them. Nobody has to hand-write a wiki page and then forget to update it.

## When the reader is an LLM

Step five is where things tend to go wrong. ReadMe generates an MCP server directly from an OpenAPI spec, with a `get-endpoint` tool for inspecting a single endpoint and an `execute-request` tool for calling the real API and returning the result. The customer's agent reads the spec, picks an endpoint and calls it.

By default, every endpoint in the spec is exposed to AI assistants, and you can switch each one on or off. If the customer's API has 180 endpoints and the agent needs only 6 for the order-lookup use case, turn off the other 174. Speakeasy's warning about 200 tools is the reason: turning every operation into a tool floods the model's context.

**Key point:** A spec for people needs to be complete; a spec for agents needs to be curated and say plainly when to use each endpoint.

The second problem is descriptions. Haidar states bluntly that OpenAPI descriptions were not designed for LLMs. "Get the status of one order" is enough for a developer, but a model needs to know when to use an endpoint and when not to. That is why the description in the example above spells out "do not use to list multiple orders".

## Limits to know up front

OpenAPI is a standard for HTTP APIs. If the customer runs an event-driven system, the relevant standard is AsyncAPI; Spectral can lint it, but ReadMe's MCP feature described above is documented as generating from OpenAPI specs, so check separately before promising anything to the customer. A spec is also only correct while it is maintained: Prism's mocks and Redoc's docs will be exactly as wrong as the spec.

Nor should "has an MCP server" be confused with "the agent uses it well". The `execute-request` tool calls the real API, so permissions and the scope of exposed endpoints are decisions to agree with the customer, not something to leave to default settings.

## Three common mistakes, and an exercise to avoid them

The first mistake is leaving the defaults in place, exposing every endpoint to the agent and then being surprised when the model picks the wrong one. The second is keeping descriptions written for people, such as a one-line summary, instead of stating clearly when to use an endpoint and when not to.

The third is treating the spec as a write-once document, not linting it in CI, and letting it drift from the code until the mocks and docs are wrong too.

The exercise: add a `GET /orders` endpoint to the YAML file above to list orders by customer. Write descriptions for both endpoints so that someone who cannot code would still pick correctly between "look up one order" and "list many orders", then run Spectral and Prism. If you have to read the schema to tell the two endpoints apart, a model will struggle too.

## What to learn first

Start with the standard, not the tools. Read the `paths`, `parameters` and `components/schemas` sections of the specification, hand-write a spec for an API you know well, then run Spectral and Prism on it. Once that is comfortable, add step five: ask whether each description is enough for a model to choose correctly.

On your CV, do not write a vague "knows Swagger". Say that you built a spec-first workflow with linting in CI, mocks for integration partners, and a curated set of endpoints for agents. Those three points show a hiring manager that you understand a spec serves both people and machines.

The spec used to be something written to close a ticket. It is now the interface that both the customer's IT team and their agents read.

**Try this week:**

- Take an internal API you are working on, write an OpenAPI spec for its three most important endpoints and run Spectral on it.
- Stand up Prism from that spec and send a request with the wrong data type to see how the mock server reports the validation error.
- Rewrite one endpoint's description in the form 'when to use it, what it needs, what it returns', then compare it with the original.

## Sources

- [Swagger (SmartBear) – official website](https://swagger.io/)

- [OpenAPI Initiative](https://www.openapis.org/)

- [OpenAPI Specification v3.2.1](https://spec.openapis.org/oas/latest.html)

- [A brief history of the OpenAPI Specification (Mike Ralphson, DEV Community)](https://dev.to/mikeralphson/a-brief-history-of-the-openapi-specification-3g27)

- [Stoplight](https://stoplight.io/)

- [stoplightio (GitHub organization)](https://github.com/stoplightio)

- [Redocly/redoc (GitHub README)](https://github.com/Redocly/redoc)

- [MCP servers – ReadMe Docs](https://docs.readme.com/main/docs/mcp-servers)

- [Generating MCP servers from OpenAPI: Lessons from building 50+ production MCP servers (Georges Haidar, Speakeasy)](https://www.speakeasy.com/blog/generating-mcp-from-openapi-lessons-from-50-production-servers)
