FDE Times dataFDE jobs open 8840 Change in open roles over 7 days, like-for-like: roles from companies we started tracking this week are left outNew in 7 days 53Companies hiring 185Remote-friendly 25%Median US pay $200kTop hirer Databricks 98
中文VI

The newspaper of the Forward Deployed Engineer

Tools

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.

ShareLinkedInFacebookX

In brief

  • OpenAPI is the standard; Swagger, Stoplight, Redoc and ReadMe are tools built on it.
  • A good spec can generate docs, a mock server, a client and an MCP server for AI assistants.
  • Do not expose every endpoint to an LLM: too many tools confuse the model, and descriptions written for people do not suit machines.
Stacked bar chart on a scale of 0 to 200: in the example there are 180 endpoints, of which the agent needs only 6 (orange section) and the remaining 174 should be switched off. A dashed line at 200 tools marks the threshold at which, according to Speakeasy, models start to get confused.
In an order-lookup use case, the agent needs only 6 of 180 endpoints. Expose every endpoint by default and the tool count approaches 200, the point at which Speakeasy finds models get confused. Source: Georges Haidar (Speakeasy); the 180-endpoint figure is an example from the article.

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:

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.

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.

Was this article useful?

Use with your AI assistantAsk Claude ↗Ask ChatGPT ↗
9 sources
Read next on the roadmap · Stage 5: DeploymentOne playbook for 20 client servers, and nothing installed on themAnsible pushes modules over SSH and deletes them after each run, so the first thing to ask IT for is an SSH account that can escalate.