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

Annotations already declare a read-only, non-destructive, closed-world read, so the safety profile is covered. The description adds real value beyond that: the discovery-only filter, the symmetric best/worst-N return shape, the 0-1 scale of mentionRate, and the rationale that excluding branded/competitor prompts keeps the weakest prompt actionable.

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 scope constraint, metric definitions, return shape, and intended question all appear up front in two sentences with no filler. The first sentence is long and parenthesis-heavy, but every clause contributes informational content.

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 absorbs that burden well by naming the returned fields and the best/worst-N structure. The main gap is the 'days' parameter, whose default 30-day window is invisible unless the agent reads the schema, and no guidance on rate of change or recency effects.

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 67%, so the schema carries most of the load. The description clarifies that topN produces both a top and bottom slice (doubling the apparent count) and that mentionRate is 0-1, but it never mentions the 'days' lookback window or the 'market' code, the latter of which is only explained in the schema.

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 and metric set (per-prompt mentionRate and response count) and sharply bounds scope to DISCOVERY prompts, explicitly excluding branded and competitor prompts. That scoping distinguishes it from a general visibility or rankings tool, though it never names which sibling covers the excluded prompt types.

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 a concrete motivating question ('which prompts are we winning or losing on') and states the exclusion rule that determines when this tool is the right one. It stops short of naming get_rankings or get_visibility_summary as the alternative when the agent actually wants branded or competitor prompt data.

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