Quick answer: A Cursor agent reasons from the context that fits in its window, which is a partial and sometimes stale view of your system, not the authoritative API contract. When the current OpenAPI spec is not part of that context, the agent fills gaps from memory, naming conventions, and similar code, which is how it hallucinates a path or a field. The fix is not a better prompt. It is making the authoritative contract reachable, so the agent has the real operations and schemas to read instead of reconstructing them.
Context and truth are different things
The agent is not connected to a live definition of your API. It sees the files you have open, the code it reads, and the snippets in the prompt. That collection is its context, and it treats the reachable context as the complete picture.
The OpenAPI document is the truth: the exact paths, methods, request bodies, status codes, and schemas the backend actually accepts. When that document is absent from the context, both can describe the same API and disagree, and the agent has no way to know which one is current. It simply works from what it can see.
Where the two diverge in practice
The failures are specific and repeatable, which makes them useful as a checklist.
| Agent behavior | What it used | What the spec says |
|---|---|---|
Calls /v1/users/list
|
A naming pattern seen elsewhere | The real path is /v1/users with pagination |
| Sends a field that no longer exists | An old example in the codebase | The field was removed in the current version |
| Omits a required header | A similar request that did not need it | The operation requires it |
| Guesses a 200 response shape | A handler from another service | The contract defines a different envelope |
| Uses the wrong content type | A copied request | The endpoint expects a specific type |
Every one of these is a context problem. The agent is capable of reading the correct path; it was simply never given the document that contains it.
Why a bigger prompt does not close the gap
Adding prose such as "use the correct endpoints" does not help, because the agent already intends to. What it lacks is the information, not the instruction. A prompt that names the spec file helps, but only if the agent actually reads the current version rather than relying on a remembered snippet.
Three practices keep the contract in the effective context.
- Keep the OpenAPI spec in the repository and open or reference it at the start of the task, so the agent reads the live version rather than a cached mental model.
- Ask the agent to quote the exact operation and schema it plans to call before writing the request, which makes a missing or stale detail visible before code exists.
- Verify the generated request against the contract after it is written, treating a match as a check, not an assumption.
The honest limits of context
Even with the spec available, context is not a guarantee. A large document can be truncated, a generated client can drift from the source, and dynamic endpoints that are not fully described will still leave gaps. The goal is not to make the agent omniscient. It is to anchor the parts that are knowable, the declared contract, and keep the unknowns explicit rather than guessed.
That distinction matters for tooling. Generated clients and MCP tools derived from the spec, the kind Powerduck produces, inherit the same source of truth, so an agent calling them is working from the contract rather than reconstructing it from surrounding code. Hand-written requests in many files have no such anchor and are where the drift concentrates.
Frequently asked questions
Does Cursor read OpenAPI automatically? The editor does not treat an arbitrary spec as authoritative unless it is part of the context or exposed through a tool the agent uses. If the file is not opened, referenced, or surfaced, the agent cannot rely on it.
Is a generated client enough, or do I still need the spec? A client helps, but clients drift if they are not regenerated when the contract changes. Keep the spec as the source and treat the client as a derived artifact that is refreshed on change.
How do I stop the agent from inventing fields? Give it the schema to read, have it restate the request shape before editing, and verify the result against the contract. Invention fills a gap; removing the gap removes most of it.
Is this a Cursor-specific flaw? No. Any agent that works from a finite context will guess when the contract is outside that context. The failure is generic; the fix is keeping the authoritative definition reachable.
The bottom line
An agent never confuses its context with anything else, because the context is all it has. When the current OpenAPI contract sits outside that window, confident-looking guesses are the expected result, not a surprise defect. The reliable fix is mechanical: keep the spec in the repo and in the task, make the agent quote the operation before it codes, and verify the request against the contract after. You cannot prompt away missing information, but you can make sure the truth is the thing the agent reads first. How this compares across the workflow is covered in the comparison hub.
Top comments (1)
A useful guardrail is to make the spec version observable in the agent’s work: pass a commit hash or content digest with the task and have the generated change cite it. Then CI can reject a client change that was produced against an older contract even when the paths happen to look plausible. “Spec reachable” becomes a checkable provenance requirement.