Best Practices for Converting OpenAPI Specs into Agent Tools

The quality of the tools you hand to an agent is decided long before conversion, in the OpenAPI spec itself. The first habit to build is a strict operationId convention. Every operation must have a unique, verb-first, readable ID such as getWeather or createWeatherReport. These IDs become the tool names the model will emit in its calls, so they must be stable, descriptive, and free of version noise. Renaming an operationId after an agent has learned to call it breaks every cached conversation that references the old name.

Write summaries and descriptions for the model, not just for human developers. The converter copies summary into the tool's description field verbatim. A summary of "Creates a weather report" leaves the model guessing about the required fields and the meaning of severity levels. Prefer a description that states the purpose, the key inputs, and one or two conventions: "Create a weather report for a location; severity is one of low, moderate, or severe and defaults to low." The model reads this text at inference time, so every concrete detail reduces the chance of a bad tool call.

Be explicit with the required array. A parameter that is genuinely mandatory should be marked required: true in the spec so it lands in the generated schema's required list. Vague schemas without required markers force the model to guess which fields the API demands, and the resulting 400 errors become agent failures your users see. Conversely, do not mark optional parameters as required just to be safe; forcing the model to invent values for fields it does not need invites hallucinated inputs.

Keep JSON body schemas shallow and well-named. Deeply nested objects with dozens of generic properties generate argument objects the model struggles to fill correctly. Break the body into a few named sub-objects with clear descriptions, reuse components via $ref where the same shape appears twice, and give every property a description. The converter inlines these component schemas automatically, so the output reflects whatever clarity you build into the components.

Use enums and defaults liberally. An enum on a query parameter such as ["metric","imperial"] tells the model exactly which strings the API accepts, dramatically reducing invalid arguments. A declared default lets the model omit the parameter entirely when the default matches the user's intent. Both constructs survive conversion untouched, and they are among the cheapest ways to make generated tools more reliable.

Review the converted output before wiring it into production. The converter is deterministic and faithful to your spec, so an odd tool usually points back to an odd spec. Count the operations, check that path parameters appear as properties, confirm request-body fields are present, and spot-check one enum and one nested object. Fixing a spec is cheap at this stage; fixing a spec after an agent has misbehaved in front of users is expensive.

Keep the number of tools per agent proportional to the task. A spec with four hundred operations produces four hundred tools, and many models handle large tool lists poorly, increasing latency and confusion. Consider splitting your API into focused tool sets per agent, or exposing only the operations each agent is actually allowed to perform. The converter makes this trivial because you can paste a slimmed-down spec, or a fragment containing only the paths you want, into the same tool.

Version your tool definitions with the API contract. When the API changes, regenerate the tools and run a regression check where the agent performs representative tasks against a sandbox. Compare the generated schema against the previous version to catch breaking changes such as a parameter that became required or a field that was removed from the body. Because conversion is instant and local, you can fold it into your CI script and fail the build when the spec's tool surface changes unexpectedly.

Do not let descriptions rot. The text that helps the model today will be stale in six months when the API adds pagination, changes default units, or deprecates an endpoint. Schedule periodic description audits alongside regular API maintenance, and re-convert after every spec release. The cost of keeping the spec fresh is tiny compared with debugging an agent that confidently calls a deprecated endpoint with outdated arguments.

Finally, test with the actual provider, not just the schema. OpenAI and Anthropic both validate tool schemas at request time, and subtle differences in what they accept appear only when you send real requests. Generate the array, paste it into a real test call, and confirm the model completes a task end to end. Schema-conversion correctness and runtime reliability are two different gates, and a mature pipeline respects both.