Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, and the description adds substantive behavior on top: private sources render as labels rather than links, MCP Registry listing IDs are fetched live and are unverified, and a failed lookup does not prove absence. Those are non-obvious operational traits an agent cannot infer from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and the sibling relationship in the first clause, then layers section semantics and caveats. It is a dense single paragraph with clause-heavy sentences, but nearly every clause carries information; only minor tightening is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so for the default payload and most section values, plus failure semantics ('missing records return nearby ID suggestions'). The 'changes' section value is left unexplained and no auth considerations are noted, so it is strong but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantic effect of specific section values ('lesson'/'gotchas' yield install/check/first-task steps with test results; 'relations', 'axes') and the default payload when sections is omitted. It does not explain the 'changes' enum value, leaving one parameter option semantically ungrounded.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one record by an ID') and enumerates exactly what a record can be (app, usecase, feature, concept, change). It explicitly anchors the retrieval to the sibling headlesson_search as the ID source, so an agent can separate it from that tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly frames the workflow (IDs come from headlesson_search) and explains that omitting sections returns the default payload, which tells the agent when to pass sections and when not to. It never states explicit exclusions or when another sibling (e.g. whats_new or feedback) would be preferable, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.