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

Annotations already cover readOnlyHint=true and idempotentHint=true, but the description adds rich behavioral context beyond that: pagination semantics (read 'pages' from first response and increment 'page'), the requirement to keep 'category' and 'per_page' constant across pages because 'total' and 'pages' reflect the filter and re-slicing, and the behavior of a page beyond the last returning an empty results[]. No contradiction with annotations.

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?

Though the description is substantial, every sentence earns its place. It front-loads the core purpose and then builds out pagination mechanics, filter caveats, sibling routing, and a bulk alternative in a logical order. No fluff, no repetition of schema details, and the structure makes it easy to scan.

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?

Given the tool's complexity (pagination, filters, five siblings, and a bulk mirror), the description covers everything an agent needs: how to page correctly, what the response shape is, how filters affect totals, when to use each alternative, and the NDJSON streaming option. The output schema exists, so the description correctly focuses on usage behavior rather than re-listing return fields.

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% and each parameter already has a solid description, but the tool description adds crucial meaning beyond the schema: it explains that 'page' should start at 1 and increment until it equals 'pages', that 'category' changes the counts and must be kept identical across pages, and that changing 'per_page' re-slices the catalogue. This interplay is not present in the schema and is essential for correct use.

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 opens with a precise verb and resource: 'Enumerate the whole approved catalogue in deterministic slug order, page by page.' It explicitly contrasts with specific lookups ('not when you are looking for something specific') and names the sibling tools it is not, so an agent can distinguish it immediately without opening schemas.

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 an explicit 'use this when' (mirroring, auditing, building your own index) and an explicit 'not when' (looking for something specific), then routes to specific siblings: search_registry for keywords, discover_capabilities for plain-language needs, list_categories for category values, and get_entry for full records. It also offers a bulk mirror alternative via NDJSON stream, leaving no ambiguity about when to call it.

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