find_low_ctr_opportunities

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint, so the safety profile is covered. The description adds real behavioral content beyond that: the filtering logic that defines a result (rank top AND low CTR AND sufficient impressions) and the concrete default thresholds that shape output volume. It still doesn't mention pagination/row-cap behavior or property-access prerequisites beyond the GSC_SITE_URL default.

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 purpose is front-loaded in a single dense sentence, followed by a clean Args block with no filler. Minor cost: the diagnostic aside lengthens the opening sentence and the max_position phrasing is imprecise rather than wasteful.

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 an output schema present, return values need not be explained, and annotations cover mutability. All six parameters are accounted for and the selection logic is clear. Remaining gap is minor: no explicit indication of how the defaults interact (e.g., min_impressions gating before or after position filtering) or of authentication expectations for a read-only GSC query.

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 carries the full burden and largely meets it: all six parameters are listed with defaults and intent, including a useful note that site_url falls back to GSC_SITE_URL. The one weakness is max_position, described as 'Only rows at or above this position' — ambiguous given that lower numbers are better, so an agent might misread the comparison direction.

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 precise, specific concept: pages ranking in top positions (position <= 5) whose CTR is at or below 2%. The parenthetical diagnoses why (title/meta rewrites or AI Overview/featured-snippet cannibalization), which clearly separates it from siblings like find_striking_distance_keywords or find_keyword_cannibalization.

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?

Usage context is implied by the diagnosis ('title/meta rewrites, or answers being shown in AI Overviews / featured snippets'), so an agent can infer the intent is to find on-page optimization candidates. However, the description never states when to use this versus get_search_analytics or get_search_by_page_query, and no exclusions are given.

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