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

Annotations already declare readOnly, idempotent, non-destructive behavior, and the description adds genuinely new operational context: pages may be unreadable ('or why a page cannot be read') and recorded changes surface on a 30-day delay. That staleness/error disclosure is valuable beyond the structured hints, though it stops short of describing pagination or caching behavior.

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?

The first sentence is a single dense clause stacking four different data categories, which hurts scanability. The final sentence about subscribers and pricing reads as promotional and buries the notable 30-day staleness fact, though that fact does earn its place.

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 well by enumerating the record's sections (sub-processor list/DTA, notice window with source URL and read date, public changes with permalinks, retirement dates). An agent knows what to expect, though it lacks guidance on missing-vendor or ambiguous-name outcomes.

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 description coverage is 100% and the single parameter is fully documented with examples, so the schema does the heavy lifting. The description's 'accepts a name, slug or domain' restates the schema rather than adding accepted-format edge cases (matching, disambiguation, partial names).

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 a specific resource (the Xither record for one vendor) and enumerates the contents an agent will receive, so the purpose is unambiguous. It does not, however, explicitly distinguish itself from siblings like notice_windows or upcoming_model_retirements, even though it mentions those same data points, leaving some overlap unaddressed.

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?

The only usage guidance is 'One vendor per call; accepts a name, slug or domain,' which hints at a bulk alternative but never names search_vendors. There is no explicit when-to-use, when-not-to-use, or routing to the sibling tools that cover notice windows and retirements.

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