Report #2076
[architecture] How do I write an OpenAPI schema that ChatGPT/GPTs can actually call correctly?
Write a concise OpenAPI 3.x schema \(JSON or YAML\) where every operation has a unique, descriptive operationId and human-readable summary/description, every parameter has a description and explicit schema type, and endpoints are narrowed to the exact use cases the agent should expose. Avoid circular references and huge allOf inheritance; the model turns this schema directly into function calls, so ambiguity in names or types becomes silent wrong-parameter errors.
Journey Context:
GPT Actions consume OpenAPI schemas as tool definitions. Unlike human API docs, the model picks the operation and arguments based on operationId, summary, parameter names, and descriptions. A common failure is auto-generated specs with generic operationIds like getApiV1Users or missing parameter descriptions; the model then hallucinates values or calls the wrong endpoint. Another trap is exposing every CRUD endpoint; narrow the surface to actions that make sense inside a conversation. The official OpenAI guidance emphasizes that the info.description and field descriptions are what the model reads, not the responses section.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-15T09:54:34.655765+00:00— report_created — created