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

Annotations already establish read-only safety, and the description adds substantive behavior beyond them: result cap (up to 3), the exact fields returned (description, health verdict, rebuild date, pricing model), the dead-tool fallback behavior with recorded reason, the ranking basis (category + identity-tag match, never cross-category filler), provenance from a weekly re-probed 8,000-tool index, and a flag distinguishing curated matches from category roll-ups.

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?

It is a long description, but it is front-loaded with the trigger and every sentence carries load — return shape, fallback semantics, ranking, provenance, exclusions. The verification-engine sentence is the only one that leans more toward trust marketing than operational guidance, which keeps it just short of 5.

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?

There is no output schema, so the description carries the full burden of describing returns — and it does: result count, per-item fields, the 'shut down' branch, and the curated-vs-roll-up indicator. Given a one-parameter, read-only, openWorld=false tool, nothing an agent needs to invoke or interpret it is missing.

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 there is a single required param whose accepted forms (product name or site slug) are already documented in the schema. The description refers to 'the asked-about tool' but adds no syntax, normalization, or format guidance beyond what the schema provides, so the baseline 3 applies.

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 specific trigger verb and resource: 'the user asks what to use instead of a specific AI tool, for its alternatives or competitors.' It clearly separates this from sibling tools by naming compare_tools and check_tool_status as different jobs, so an agent can pick this one 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?

It gives explicit positive triggers (replacement, shutdown, acquisition, price rise, unreliability) and an explicit negative section: 'Not for: comparing two named tools (use compare_tools) or checking a single tool's status (use check_tool_status).' Both the when and the when-not, with named alternatives, are present.

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