Optimization Tips for Higher-Quality Generated Agent Tools

The single biggest optimization for converted tools is reducing the number of tools a model must consider. Every additional function in the request consumes context, adds inference time, and increases the chance of a wrong selection. Before you convert, prune the spec to the operations the agent actually needs. A support agent does not need the admin's delete-user endpoint. Generating ten focused tools from a trimmed spec almost always outperforms generating two hundred unfocused tools from the full API, and the converter makes re-generating after pruning a ten-second job.

Dereference your spec before conversion to keep the output predictable. The converter already resolves local component references, but you can make the process even cleaner by exporting a fully dereferenced copy of your spec from your API tooling first. That guarantees no hidden references are lurking in unusual places, such as references inside examples or nested parameter objects, and it makes the generated JSON easier to diff between versions because the structure stays flat.

Flatten deeply nested bodies in the spec so the model has fewer decisions to make. A request body shaped as {"data":{"attributes":{"name":...}}} forces the model to reproduce the wrapping objects exactly, which invites mistakes. Where the API contract allows it, move required fields to the top level of the body schema and keep nested wrappers only for genuinely grouped data. Fewer levels of nesting correlates strongly with fewer malformed tool arguments in practice.

Trim your enums and constraints to the values that matter. An enum with two hundred colour names is context for the model, most of it never used. Remove deprecated or rarely used values, and set meaningful defaults so the model can omit parameters entirely when a sensible default exists. Every keyword, enum value, and property description in the tool schema is context the model must process, so the leanest accurate schema is also the fastest and most reliable.

Write descriptions that disambiguate overlapping tools. When two endpoints could both satisfy a request, for example creating a draft report versus publishing a report, the model decides based on the description text. Include the distinguishing trigger in each: "publishes the report so external users can view it" versus "saves a draft that only the author can see." This kind of disambiguation is the highest-leverage description practice for multi-tool agents and costs nothing beyond a sentence in the spec.

Group related operations into composite tools when the workflow is fixed. If the agent always creates a report and then publishes it, a single "createAndPublishReport" tool with both inputs is easier for the model to call correctly than a fragile two-call sequence. The converter will happily generate the composite if you add it to the spec, and it reduces round-trips. Reserve composites for sequences that are genuinely always coupled; over-composing removes useful flexibility.

Cache the generated definitions and version them like code. Conversion is deterministic, so a given spec revision always yields the same JSON. Store the generated arrays in your repository, regenerate them in CI on every spec change, and review the diff. This makes tool changes visible in pull requests, catches accidental schema drift before it reaches production, and gives you a rollback point if a tool behaviour regression appears after a release.

Instrument tool-call quality in production. Log every tool name and argument set the model emits, then measure the rate of validation failures, retries, and human corrections per tool. The data will quickly identify the tools that confuse the model, and the pattern is usually the same: vague description, missing required marker, or an unclear enum. Feed those findings back into the spec and re-convert. Optimization becomes an ongoing loop driven by evidence rather than guesswork.

Parallelise with care. Some providers let agents call multiple tools in one response, which can dramatically speed up workflows, but it also multiplies the cost of a single bad schema because several calls can fail at once. Optimize the schema quality of the tools that are most likely to be batched, verify multi-call behaviour with a test conversation, and keep destructive operations out of parallel batches regardless of schema quality.

Finally, benchmark a representative task suite before and after every tool-generation change. Keep a handful of end-to-end tasks, such as "create a metric-units weather report for Paris and publish it," and measure success rate, latency, and token usage. Because the converter is free and instant, you can A/B different spec phrasings and required arrays empirically, then keep the version that wins. Data-driven tool tuning is the closest thing to a guaranteed path to a better agent.