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.…