The Complete Guide to Converting OpenAPI Specs into Agent Tools

Function calling changed how agents interact with the world. Instead of parsing the model's plain-text reply and hoping it matches an API call, the model now receives a description of the tools it may invoke, decides which one fits the user's request, and returns a structured JSON object with the function name and arguments. The hard part is writing those tool descriptions by hand for every endpoint of a growing REST API. An OpenAPI converter solves that problem by turning the spec you already maintain into tool definitions you can paste straight into your agent.

OpenAPI 3.x organises an API as a set of paths, and each path can carry several HTTP operations. The converter iterates over every path in the spec's paths object and, for each supported method, reads the operation object. Each operation is one callable tool. The operationId becomes the tool's name, which is why keeping operationIds unique and meaningful in the spec is the single highest-impact habit you can adopt. When an operationId is missing, a readable fallback such as get_weather_city is generated from the method and path so the output stays usable.

Parameters are the next piece. An operation can declare parameters that live in the path, like /weather/{city}, or in the query string, like ?units=metric. The converter reads each parameter's name, location, and JSON Schema, then adds it as a property of the tool's argument object. A parameter marked required: true lands in the schema's required array, which tells the model it must supply a value. Enums, defaults, and descriptions are preserved so the model knows its options before it picks a value.

Request bodies carry the payload for POST, PUT, and PATCH operations. The converter looks inside requestBody.content for the application/json media type and reads its schema. When that schema is an object, its properties are merged into the tool's argument object and its required fields are appended to the required array. Nested structures work too: an array of strings, a property that references another component, and even multi-level objects are resolved recursively. If the body has no schema at all, a generic object is generated so the operation still becomes callable.

Real-world specs rely heavily on $ref pointers to avoid repeating schemas. The converter resolves local references such as #/components/schemas/Severity and #/components/parameters/City by walking the spec's components tree and inlining the resolved definition into the tool schema. Cyclic references are guarded with a seen-set so a self-referencing schema degrades gracefully into an object with a descriptive note instead of crashing the conversion. This means you can point the tool at a production spec that uses components heavily and still get a clean result.

The output is provider-shaped. OpenAI's format wraps each tool in {"type":"function","function":{"name","description","parameters"}}, where parameters is a JSON Schema object. Anthropic uses the flatter {"name","description","input_schema"}. The converter emits both arrays from the same parsed spec, so you never have to maintain two handwritten versions of your tool definitions. If you later switch providers or support both in one product, the same spec feeds both tool arrays.

Because the conversion runs entirely in the browser, the spec never leaves your machine. This matters for teams whose APIs are under NDA or contain internal endpoint names they would rather not upload to a third-party service. Paste, convert, copy, and the only place your spec ever existed is your own textarea. There is no sign-up, no rate limit, and no backend to provision, which makes the tool convenient for a quick spike during a standup as much as for a careful production rollout.

A typical workflow looks like this. Export your API spec from your gateway or codebase as JSON. Open the converter and paste it in. Press convert, skim the two output arrays to confirm the tool count matches your endpoint count, then copy the array you need into your agent's tool configuration. Run a test conversation where the model is asked to perform a task that requires the API, and verify the model selects the right tool and passes valid arguments. Adjust descriptions in the spec when the model chooses the wrong tool, and re-convert.

The descriptions you write in the spec carry directly into the tool, and they are the lever that controls model behaviour. A terse summary like "get weather" is far weaker than "Get current weather for a city including temperature, condition, and humidity; use metric units unless the user prefers imperial." Writing endpoint descriptions with the model in mind, naming the use cases and the edge conventions, is the difference between an agent that reliably picks the right tool and one that guesses.

Start with a small spec, verify the output, and then feed it your full API. The converter's handling of path and query parameters, JSON bodies, required fields, and component references covers the vast majority of real-world OpenAPI documents, so most teams can move from "handwritten tool JSON" to "converted from spec" in a single afternoon and never look back.