Some doc patterns work fine for humans because we fill in gaps automatically. A reader sees "the user ID" and assumes it is the ID of the user they care about. A model assumes a plausible value and submits it. Here are the patterns that come up most often, and what to do about them.
Vague parameter descriptions
"The timeout." A human reading this checks the API client default. A model picks a guess.
Bad:
timeout (integer): the timeout.
Better:
timeout (integer): request timeout in seconds. Between 1 and 60. Defaults to 30.
Type, units, range, default. All four matter.
Required fields shown the same as optional
If your reference puts required fields in the same list as optional ones with no visible difference, models will skip them. So will humans on a tight deadline.
Mark required fields explicitly. Mark them in prose, in the schema, and in every example.
Examples that disagree with the schema
A common pattern: the schema says user_id, the example uses userId. Either is fine. Mixed is not. The model will pick one and stick with it across the rest of the session.
Pick one form and use it everywhere. If you change a name, change every example in the same pass.
Auth in prose only
If your only mention of the auth header is "include your API key in the request," many models will guess Authorization: Bearer KEY even when your scheme is X-Api-Key: KEY. The fix is one curl example, repeated near every endpoint that needs it.
Pagination details split across pages
If pagination params live on a separate page from the endpoint that uses them, a model reading the endpoint page in isolation will guess. Repeat the params on the endpoint page, even if it duplicates a sentence.
Inconsistent terminology across pages
When one page calls something a "project" and another calls it a "workspace," a model treats them as different things. The reader might catch the conflict and resolve it. The model usually does not.
Pick the canonical term, list any synonyms once in a glossary, and stop using the others. Do a global find on the docs whenever you rename a concept.
Configuration that varies by environment
Pages that say "the base URL is api.example.com in production and api-staging.example.com in staging" without an example of each leave the model to guess. The model often emits the production URL even when the user is clearly working in staging.
Show full examples for each environment. List the base URLs in a single place, near the top of the auth section, with the conditions under which to use each.
Response shapes hidden in narrative
Some docs explain response bodies in prose: "the response includes a user object with the fields above, plus a created_at timestamp." A schema example is missing. A model has to assemble the shape from the prose, and often gets the order or nesting wrong.
Always include a JSON example of the response, alongside the prose. Even an incomplete example helps. The model uses it to anchor what the actual shape is.
The pattern behind these
The thing all of these have in common: anywhere a human would skim and infer, a model will guess. The fix is the same in each case. State the thing explicitly, in prose or in an example, on the page where the call lives.
