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

Annotations already establish read-only behavior. The description adds valuable context beyond that: it requires an agent API key, has no financial cost, and returns scored, ranked queries. These details disclose operational requirements and output characteristics not present in the annotations or schema.

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 description is extremely concise: three short clauses that cover the core purpose, cost, a parameter variant, and an auth requirement. Every phrase adds information, with no redundancy or filler. The most important content is front-loaded.

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?

For a straightforward read-only list tool with three self-explanatory parameters, the description covers the essential aspects: output type, scoring/ranking, cost, auth, and the main parameter variant. It lacks a detailed explanation of limit's default behavior or the exact scoring methodology, but those are not critical for correct tool invocation.

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 descriptions are absent (0% coverage), so the description must compensate. It clarifies questionsOnly ('question-shaped queries') and implies siteId via 'for a site'. The limit parameter is left to the schema, but its meaning is standard. Partial compensation for the non-obvious parameter is provided.

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 clearly states the tool's purpose: it lists winnable search queries for a site, scored and ranked. It distinguishes this from sibling list tools like list_articles and list_sites by specifying the unique resource (opportunities). The verb 'list' is implicit in the name, but the description makes the output unambiguous.

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 description provides clear context for when to use the tool: to retrieve winnable search queries for a site, with a note that there is no cost. It also explains the questionsOnly variant. However, it does not explicitly contrast with alternative tools or state when not to use it, so it falls short of a 5.

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