Common Errors in OpenAPI-to-Tool Conversion and Their Fixes

The most common failure when converting an OpenAPI spec is invalid JSON. A trailing comma after the last property, an unescaped double quote inside a description, or a missing closing brace are all rejected by the JSON parser, and the tool refuses to produce output until the document parses cleanly. The inline error shows the exact location reported by the parser, so the fix is usually a quick inspection of the line named. If your spec came from a generator that outputs YAML, remember to export the JSON flavour, not YAML, before pasting it into the converter.

The second classic error is a spec without a usable paths object. The converter cannot invent endpoints, so a document that only defines components, or one that places operations at the top level, produces a clear error: no paths found. This usually happens when someone pastes a partial fragment or a security schema instead of a full API description. Paste the complete document, or at minimum the fragment that contains the paths you want to convert.

Missing operationIds are handled gracefully but are still a warning sign. The converter generates a fallback name from the HTTP method and the path, such as get_weather_city, which is perfectly callable. The trouble is that fallback names are brittle and machine-generated, so they can collide or read awkwardly, and the model will emit them verbatim. Add explicit, unique operationIds to every operation and re-convert; the generated tool names then read like real function names and stay stable across spec versions.

Unresolvable $ref pointers produce silently degraded output. If a schema references #/components/schemas/Missing and no such component exists, the reference resolves to nothing and the property is dropped or replaced by an empty object. The converter guards against infinite recursion, but it cannot invent a schema you forgot to define. Validate your spec with a linter that reports broken references before converting, and check the generated JSON for any property that unexpectedly vanished.

Request bodies that are not JSON objects are another subtle trap. If an operation declares requestBody.content["text/plain"] or a schema whose type is string, there are no object properties to merge, so the converter wraps the whole thing under a single body property. That is a sensible fallback, but models reason about it less well than they reason about named fields. Where possible, structure your payloads as JSON objects with descriptive property names so the generated argument schema is genuinely usable.

Duplicate parameter names between path, query, and body can silently overwrite each other. OpenAPI allows a path parameter and a body field to share a name, but the tool schema is a flat object with unique keys, so the later source wins. The practical fix is to keep names unique across the operation or to rename body fields that collide with path parameters. Check the generated properties list after conversion to confirm every input you expect is present exactly once.

Empty descriptions generate weak tools. An operation with no summary and no description becomes a tool whose description is the boilerplate "Call the GET endpoint at /weather/{city}." The model will still call it, but it has no guidance on when to use it or what to pass. Adding a one-line summary to the spec transforms the tool's usefulness, and because conversion is instant, this is the cheapest quality upgrade available in the whole workflow.

Forgetting to update tools after a spec change is not a conversion error, but it is the most expensive error downstream. Teams convert once, deploy the tools, and then update the API while the agent keeps calling the old schema. The symptoms, arguments rejected by the server or fields silently dropped, look like model failures even though the tools are stale. Regenerate the definitions on every spec release and diff them in review, exactly as you would diff an SDK client.

Finally, providers have different schema strictness. A tool that passes OpenAI's validation can be rejected by Anthropic if it contains an unsupported keyword or an unexpected structure. If you paste the converted array and the provider returns a validation error, read the message, adjust the offending schema in the spec, and re-convert. Testing the generated JSON with the actual provider is the only way to be sure, schema validity is not enough.

Almost every conversion problem traces back to the spec, not the tool. Keep the document valid JSON, keep paths present, keep operationIds unique, keep references resolvable, and keep bodies as clean JSON objects, and the converter will faithfully turn your API into tools that behave the way you intended.