find_opportunities

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by explaining that CTR is benchmarked against this site's own CTR-by-position curve rather than a global average, but it says nothing about the position band defaults that define 'striking distance' or how min_impressions/top_n shape 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?

A single sentence with the actionable framing ('Quick wins') front-loaded and three parallel clauses that each carry information. No padding, though the parenthetical CTR clause is slightly dense relative to the rest.

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 nine parameters and no output schema, the description does useful work by defining the three result categories an agent will receive. It remains incomplete on how the position band, impression threshold, and top_n constrain each of those categories, and it never states that results are limited/scored.

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 coverage is 56%, and notably position_from, position_to, and top_n carry no schema descriptions at all. The description partially compensates by tying 'ranking below 20' to the position ceiling and 'top positions' to the lower bound, giving the position band meaning, but it leaves min_impressions, top_n, and the interaction between days/start_date/end_date unexplained.

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 the resource precisely by enumerating three concrete finding types (striking-distance query/page pairs, low-CTR top positions, content gaps ranking below 20), which tells an agent exactly what this tool returns. It is distinguishable from siblings like performance_query or content_decay by its 'opportunity' framing, though the verb itself is left to the tool name rather than stated in the description.

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?

'Quick wins' implies a use case (finding actionable improvement candidates) but the description never says when to pick this over performance_query, content_decay, or query_segments, nor any prerequisites such as needing Search Console data for the site. No exclusions or alternative routing are given.

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