Turning OpenAPI Specs into LLM Tools

OpenAPI (formerly Swagger) is a machine-readable format that describes a REST API's endpoints, parameters, request bodies and responses using version-specific Schema Objects for data shapes; OpenAPI 3.1 and later align these with JSON Schema, while earlier versions differ. Since most LLM tool-calling systems, including MCP and native function-calling APIs, already expect JSON-Schema-shaped parameter definitions, the endpoint and parameter portion of an OpenAPI document maps fairly directly onto a tool definition: the path and method become the tool's identity, the parameters and request body become its input schema, and the summary or description fields become the tool's description. Several open-source converters (such as openapi-to-mcp style generators, or lightweight scripts built on libraries like openapi-schema-validator) automate this mechanical mapping. The harder, non-mechanical part is curation: production OpenAPI specs frequently describe hundreds of endpoints, many overlapping or rarely used, and their descriptions are written for engineers integrating code, not for a model deciding whether to call something. Practitioners typically prune the spec down to the handful of endpoints a given use case needs, rewrite ambiguous parameter descriptions in plain language, add example values, and flag irreversible or sensitive actions explicitly, since OpenAPI has no native concept of 'this deletes data permanently.' A common misconception is that feeding an entire large OpenAPI file to a model as tools works out of the box; in practice, tool count and description clarity both strongly affect whether the model picks the right tool and fills in arguments correctly.