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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds behavior they cannot express: default and max page size (10/20), the full sort order (impact desc, then published date desc with unpublished last, then ID), the live-pagination invalidation rule, and the fact that rows carry up to 10 linked prompts plus a nested prompt cursor. That is substantial operational context beyond 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?

Information-dense and front-loaded with the resource and pagination default, with every clause carrying operational detail. It reads as a run-on chain of clauses rather than clean sentences, which slightly hurts scanability, but no statement is wasted.

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?

For a 12-parameter, read-only paginated list tool with an output schema, the description covers pagination mechanics, ordering, cursor semantics, freshness/invalidation, and routing to the detail tool. Return-value detail is rightly delegated to the output schema. A mention of the required siteId/subjectKind precondition would close the remaining gap, though the schema carries that.

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 75%, so most filters are documented, but the description still adds meaning: it supplies the default page size (10), which the schema omits, and clarifies filter-preservation semantics while following cursors. The 'no Scan/date-history filter' note implicitly bounds what the filter parameters can express. Minor gaps remain on parameters like narrativeId, which neither schema nor description explains.

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?

The description names the specific resource (the Site or Topic current recommendation board) and its key characteristic (paginated before enrichment), letting an agent distinguish it from the singular get_recommendation sibling. It stops just short of a clean verb+resource statement, relying on jargon like 'board' and 'enrichment', but the intent is unambiguous.

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?

It gives concrete routing: follow nextCursor to paginate, route to get_recommendation for a recommendation's brief/evidence/lifecycle, and restart pagination after board/content changes. It also states an explicit exclusion ('No Scan/date-history filter'). It lacks a statement of when NOT to use it versus other list siblings like list_prompts, but context is strong.

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