Report #3668
[architecture] How do I design an API so ChatGPT \(and similar agents\) can discover and call it correctly from a GPT Action?
Publish a valid OpenAPI 3.x schema and wire it into the GPT Action. Write \`info.description\`, \`operationId\`, \`summary\`, and every parameter/response \`description\` as if they are prompts: the model uses these strings to decide which endpoint to call and what JSON arguments to generate. Keep schemas flat, use enums with descriptive names, and prefer deterministic IDs over natural-language slugs.
Journey Context:
GPT Actions are function calls driven by an OpenAPI schema; the schema is literally the prompt that tells the model what tools exist. Vague descriptions cause the model to choose the wrong operation or omit required parameters. Many developers treat OpenAPI as human documentation, but the model cannot browse your docs before calling. The design decision is to make the schema itself a precise, concise intent-description layer. The tradeoff is verbosity: overly large schemas eat context and confuse routing, so describe each operation precisely without bloat.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-15T17:53:39.695348+00:00— report_created — created