Verified against the deployed .md exports on 2026-08-18. Across the 350 REST operation pages, the median description between the H1 and the first section is 42 characters — "Create a call." is typical. 173 pages have 40 characters or fewer. Seven have no description at all (every operation under /docs/apis/rest/video/streams/). Only 4 of 350 contain any usage guidance at all, measured as any phrase along the lines of "use this when", "instead of", or "rather than".
A model choosing between operations gets nothing to choose on. Nothing in the corpus says when to create a call with POST /Calls versus issuing a call command, when list-resources is the right call versus get-resource, or which of the several address endpoints applies to a given resource type. The information exists — it is in the guides — but it is not attached to the operation, so retrieving the operation does not retrieve it.
Each operation export should open with what the operation does, when to reach for it, and what to use instead when it is the wrong choice. The source is the @doc strings in specs/, so this is ordinary repo work with no upstream dependency, and it can be done incrementally per resource group rather than as one sweep.
Scope note: #562's manifest routes between products (Agents, RELAY, SWML, REST, Compatibility). This routes between operations inside one product, which the manifest deliberately does not model. The two should not be merged.
This is the "purpose, when to use" half of #564's checklist. #564 was closed because its stated premise (a repeated navigation tree in the exports) did not hold. Audit §8.
Verified against the deployed
.mdexports on 2026-08-18. Across the 350 REST operation pages, the median description between the H1 and the first section is 42 characters — "Create a call." is typical. 173 pages have 40 characters or fewer. Seven have no description at all (every operation under/docs/apis/rest/video/streams/). Only 4 of 350 contain any usage guidance at all, measured as any phrase along the lines of "use this when", "instead of", or "rather than".A model choosing between operations gets nothing to choose on. Nothing in the corpus says when to create a call with
POST /Callsversus issuing a call command, whenlist-resourcesis the right call versusget-resource, or which of the several address endpoints applies to a given resource type. The information exists — it is in the guides — but it is not attached to the operation, so retrieving the operation does not retrieve it.Each operation export should open with what the operation does, when to reach for it, and what to use instead when it is the wrong choice. The source is the
@docstrings inspecs/, so this is ordinary repo work with no upstream dependency, and it can be done incrementally per resource group rather than as one sweep.Scope note: #562's manifest routes between products (Agents, RELAY, SWML, REST, Compatibility). This routes between operations inside one product, which the manifest deliberately does not model. The two should not be merged.
This is the "purpose, when to use" half of #564's checklist. #564 was closed because its stated premise (a repeated navigation tree in the exports) did not hold. Audit §8.