When every page is the same shape, nothing stands out to a matcher

Identify every block that is identical across endpoints: the authentication preamble, the rate limit paragraph, the error code table, the pagination explanation, the response envelope description. Each of these currently exists once per endpoint and is producing near-identical passages across the whole reference.

Move each to a single page of its own and replace it on the endpoint pages with one sentence that states the essential fact and links onward. Authentication becomes a line naming what must be sent. Errors become a line naming the two or three failures specific to this call, with the general table elsewhere.

The result is that most of the text on an endpoint page is now about that endpoint. That is the whole objective. A page whose passages are mostly unique to it will win the questions that are about it and lose the questions that are not, which is the behaviour you want and the opposite of what generated uniformity produces.

Under or beside the table, write one line per parameter that carries everything: the name, whether it is required, the type, what it does, and the default. Something like customer_id is required and is the identifier returned when the customer was created; sending an unknown one produces a not found response.

This looks like duplication and it is, deliberately. A table row is meaningful only in the context of its header, and that context is exactly what does not survive a passage boundary or a truncation. A sentence carries its own context in every word of it.

Take the same care with tables whose meaning depends on something a converter cannot keep: a merged header spanning two columns, a colour indicating deprecation, a dagger pointing at a footnote. All three become nothing. Whatever those devices were expressing has to be written into the cells themselves or into the prose beside them.

Give every endpoint its own worked example with real-looking values rather than placeholder tokens, showing every required field. Then show the response it actually produces, in full, including the fields people ask about most and not only the two that are interesting.

Add a second example for the common variation: the paginated case, the filtered case, the one with the optional parameter that everybody eventually needs. Two concrete examples answer more questions than a complete parameter table does, because most reference questions are really requests for a template to copy.

Write a sentence above each example saying what it does. That sentence is what a matcher has to work with, since code alone gives a meaning-based matcher very little to hold on to. Show me how to list customers created this month is answered by prose that says this lists customers created within a date range, sitting immediately above the code that does it.

Decide which version the assistant is allowed to answer from, and index only that. If the reference is crawled, keep the crawl inside the current version's paths. If it is uploaded, upload one version's material. Two versions in one index is a machine for producing confidently wrong answers.

Where older versions have to remain answerable because customers are still on them, the version has to be in the wording of the text and not only in the path. State it in the opening sentence and beside every path in the body, so a passage extracted from the old reference announces that it is the old reference. A version that exists only in a URL segment is a version that vanishes the moment the passage is quoted.

For a deprecated version, the most valuable page is not the reference at all. It is one page saying this version is deprecated, here is the date it stops working, here is the current equivalent of each call. That page answers the question the customer actually has, which is what do I do now.

The characteristic failure here is a fluent, well-formatted answer assembled from boilerplate belonging to a different call. Somebody asks what the rate limit is for one endpoint, and the passage retrieved is the shared rate limit paragraph as it appears on another page. It is cited correctly. It may even be right. Nothing in the answer indicates which endpoint it came from.

The version of this that costs real money is the parameter answer. A question about required fields is answered from a table fragment, the name column having been left behind, and the reply lists types and requirements that cannot be checked against anything. The developer builds against it, gets a validation error, and concludes the documentation is wrong.

Worse still is the correct answer about the wrong version. It is specific, it is confident, and it describes a path that was removed two releases ago. The developer trusts it, because reference documentation is the one place they expect precision, and spends an afternoon establishing that their own code was fine all along.