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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful provenance context: this is official documentation, not a tested ranking or an account-access guarantee. That framing materially affects how an agent should interpret and present results.

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?

Three tight sentences, front-loaded with the core action and scope before the filter hint and the caveat. Every sentence carries weight; the sole weakness is that the caveat could be slightly more compact.

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?

An output schema exists, so return values need not be described. For a read-only, zero-required-parameter comparison tool, the description covers action, scope, filter role, and provenance caveats. The only gap is the undocumented language parameter.

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 0%, so the description must compensate. It hints at the filter semantics ('shortlist documented self-managed options' maps to selfHosted, 'the seven products' maps to products) but never explains the language parameter or how product selection interacts with the comparison. Partial compensation only.

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 verb ('Compare') and resource ('source-backed capabilities and explicit unknowns for the seven products'), which is easily distinguished from the get_*/search siblings. It does not, however, explicitly name a sibling or boundary case to differentiate against. Clear but no sibling differentiation.

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?

'Filters can shortlist documented self-managed options' implies when the tool is useful (narrowing a comparison), but there is no explicit when-to-use vs. when-not, and no alternative tool is named. Usage is only implied.

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