Why an API's description field helps an AI agent decide which endpoint to call

Four of the five encounter operations in the post take an {encounter_id} in the path, and only POST /encounters does not ^[6][15]. An agent that has created nothing yet can prune those four on argument availability alone, before it reads any prose. That prune works only if the required path parameter survives into the tool schema the model is handed.

Whether it survives depends on the generator. The post is explicit that an OpenAPI document does not become an LLM's system prompt. Depending on the stack, the spec may be transformed into function definitions, JSON Schema, MCP tools or another representation before the model sees it ^[4]. The claim about descriptions is correspondingly narrow. The information in an API contract "can become part of the information the model uses to decide what to do", the post's author wrote ^[17]. So the first check is which fields your generator carries through and which it drops.

The clinical workflow in the post runs five steps: create encounter, start session, send audio, complete session and generate note. That leaves four ordering dependencies to get wrong ^[10][16]. A developer picks those up from the quick start, the API reference or a tutorial ^[11]. The agent may see five separate tools instead ^[11]. The suggested repair states the dependency where the agent is already looking: the session "must already exist and must be active", and "Do not call this endpoint before a session has been created or after the session has been completed" ^[13].

"The above API description is not prompt engineering but better API documentation written for LLMs," the post's author wrote ^[9]. For the example shown, that holds. The added sentences say when to use the operation, what the returned encounter_id is for, and when not to call it. Each of those is a fact about the API that a human reader was getting somewhere else ^[8][11].

The traffic figure comes from one dashboard on one documentation site ^[1]. For it to say anything about another API, agents would have to be fetching those docs at comparable rates, and the analytics would have to be classifying agent requests correctly. The post gives the share without volumes or a classification method ^[18]. The design argument holds at one agent anyway, because what constrains this reader is a tool definition and a context window ^[3].

Description text is not free. Every operation's summary and description sits in the tool list the model reads, and that list competes with everything else in the context window ^[3]. Traditional API documentation often focuses on the happy path, the post says ^[14]. Both of the rewritten descriptions in it carry an explicit "Do not" sentence ^[19].