OpenAPI for Agent Tools

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

OpenAPI can be used as a source contract for agent tools because it names operations, describes parameters and request bodies, and defines response schemas.

## Core Explanation

An agent tool is only as reliable as its contract. OpenAPI provides the HTTP side of that contract: paths, methods, operation identifiers, parameters, request bodies, response shapes, and security requirements. Tool runtimes can then derive model-facing tool names, argument schemas, and call wrappers from the API description.

The conversion should not be purely mechanical. Destructive operations, authentication scopes, rate limits, pagination, and user confirmation policies need explicit handling before an API operation is exposed to a model.

## Source-Mapped Facts

- The OpenAPI Specification defines an Operation Object as a description of a single API operation on a path. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- The OpenAPI Specification says an operationId is a unique string used to identify an operation, and tooling may use it to identify the operation. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- The OpenAPI Specification says the Schema Object allows definition of input and output data types and is a superset of JSON Schema Draft 2020-12. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- The Model Context Protocol tools specification says an MCP tool definition includes a name, a human-readable description, and an inputSchema for expected parameters. ([source](https://modelcontextprotocol.io/specification/2024-11-05/server/tools))

## Further Reading

- [OpenAPI Specification v3.1.1](https://spec.openapis.org/oas/v3.1.1.html)
- [Model Context Protocol Tools Specification](https://modelcontextprotocol.io/specification/2024-11-05/server/tools)
- [OpenAI Function Calling Guide](https://developers.openai.com/api/docs/guides/function-calling)