OpenAPI to Tool Definitions
Turn an OpenAPI 3 document into OpenAI and Anthropic tool definitions, with every $ref inlined and a map of which argument goes in the path, the query or the body.
From 4 operations in the document, 1 left out. Every definition below is sent on every request that offers it, whether or not the model calls it.
- Operations in the document
- 4
- Operations skipped
- 1
- Arguments across all tools
- 6
- OpenAI form, characters
- 1,660
- Estimated tokens (OpenAI form)
- ≈ 415
- Requests go to https://api.example.invalid/v1. The base URL is not part of a tool definition — your executor has to hold it, along with authentication.
- listOrders.status has no description. An undescribed argument is the usual reason a tool gets called with nonsense.
- listOrders: the header parameter "X-Request-Id" was left out. Headers are usually the caller's job, not the model's — tick the box if this one really is an argument.
- DELETE /orders/{orderId} is marked deprecated and was left out. Tick the box to include it.
$ref is inlined, because a tool definition cannot contain one; a reference to another file is not fetched and a recursive one becomes an open schema, both reported above. Path parameters are always required. Authentication is never turned into an argument — a model should not be asked for a credential — so your executor holds the base URL and the headers. Response schemas are ignored entirely: they describe what comes back, and a tool definition only describes what goes out. Token figures are characters ÷ 4 and are estimates, not a tokenizer's count. Everything on this page runs in your browser. Nothing you paste is uploaded, logged or sent anywhere.An OpenAPI document and a set of tool definitions describe the same thing from opposite ends. The spec is written for a developer who will read the whole page; the tool definition is read by a model that sees only the name, the description and the argument list, in a context it is also using for everything else. So the conversion is mostly mechanical and the two places it stops being mechanical are the two that decide whether it works.
The description is the tool
A summary written for a docs page — “List orders” — tells a model nothing about when to reach for this rather than the search endpoint. That is why the length limit above exists in both directions: long descriptions are billed on every request, and empty ones are the reason a tool gets called at the wrong moment with plausible arguments. The list underneath names every operation that arrived with neither.
Do not ship all of them
A spec with 200 operations converts to 200 tools, and offering 200 tools makes the model worse at picking any of them as well as costing you the whole schema on every turn. The useful output of this page is usually a handful: filter by path prefix, generate the ones an agent actually needs, and keep the rest in the spec where they came from. The argument-location map is there because the tool definition alone cannot tell your executor whether status belongs in the query string or the body — the spec knew, and that knowledge would otherwise be lost in the conversion.