Short answer: An agent hallucinates an API call because it is predicting the next token, not reading your server. Without a contract, it fills in the endpoint, parameters, and body from patterns and partial code. The call is the most plausible guess, not knowledge. Giving it a machine-readable contract is the direct fix.

Why the guesses are so convincing

REST APIs follow conventions. Paths are plural nouns, methods are predictable, and bodies mirror the resource. A model trained on millions of codebases produces a call that fits the convention perfectly, which is why it passes review and fails at runtime. The convention is the camouflage.

Where the guesses break

  • Paths: the real endpoint is /v2/orders or uses a verb the model did not expect.
  • Field names: the API uses billing_address and the model writes address.
  • Types: an id is a string in the API and a number in the guess.
  • Auth: the header name or scheme is different from the default.

Why a contract changes the behavior

With the OpenAPI file compiled into tools, the agent does not predict the endpoint. It reads the operation, takes the typed arguments, and makes a call that is valid by construction. The model is still predicting, but it is predicting over a correct description instead of a remembered pattern.

What does not fix it

More chat context helps only if it is current and complete, which it rarely is. A maintained contract is the only artifact that is both authoritative and machine-readable.

This is part of the Powerduck vs Cursor comparison. Continue with the API testing workflow.