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

Annotations already establish read-only, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description adds genuinely useful traits beyond that: data freshness ('as Xither last read them'), the 50-row result cap, and inclusion of the source URL and read date so staleness is visible. It doesn't cover pagination or what happens when no rows match.

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 what the tool returns, then constraints, then scope limitation. Dense and semicolon-heavy but every clause carries information; nothing is padding.

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 fully compensates by enumerating the returned fields (model, date, vendor-named replacement, verbatim table row, source URL, read date) plus ordering, limits and coverage caveats. An agent has everything needed to call and interpret it.

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%, with both parameters documented (vendor as name/slug/domain, within_days default 90, max 365), so the baseline is 3. The description largely restates those bounds; the only added element (at most 50 rows) is a result constraint rather than parameter meaning.

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 resource (model and API retirement dates from vendor-published retirement tables) with clear ordering (soonest first) and enumerates the returned fields. An agent can distinguish this from lookup_vendor, notice_windows and search_vendors without opening any 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?

Gives clear operating context: optional vendor filter, within_days defaulting to 90 and capped at 365, and a hard 50-row limit. It also states a scope boundary ('Covers only vendors whose retirement tables Xither reads'), which functions as an implicit when-not, but it never names a sibling tool as an alternative for out-of-scope vendors.

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