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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, and the description adds real substance on top: it explains that the sections are derived heuristics and explicitly caveats that 'Expected CTR by position is a rough industry curve, not a promise,' which is important for interpreting the output. It stops short of noting cost/latency of pulling Ads and GA4 joins, but the interpretive caveat is more valuable than most.

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 one sentence, followed by a scannable bulleted section list where each bullet defines one output category and its actionable interpretation. No filler sentences or restated tool name.

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 and high parameter coverage, the description covers what an agent needs: required site_url context is implied, optional joins are explained, and section contents are summarized. It does not address failure modes (missing Search Console access, mismatched Ads/GA4 accounts), which for a 7-parameter cross-service tool would be the remaining gap.

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 86%, so the schema carries most parameter documentation. The description still adds consequence-level meaning by explaining what ga4_property_id and ads_customer_id enable ('possible savings', 'SEO work that would cut ad spend'), which is more than the terse 'Adds paid vs organic overlap' schema text conveys.

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 first sentence states a specific verb and resource ('Find where organic search can grow'), names the primary data source (Search Console) and the optional joins (GA4, Google Ads). The four-section breakdown ('striking_distance', 'low_ctr', 'pages_without_clicks', 'paid_overlap') makes it clearly distinct from siblings like gsc_search_analytics or get_data, which return raw rows rather than curated opportunities.

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 gives clear context for when each mode applies: 'paid_overlap (with Google Ads)' and 'with their GA4 traffic when a property is given' tie the optional parameters to the additional sections they unlock. It does not explicitly say when to prefer this over gsc_search_analytics or get_data, so alternative routing is left implied rather than stated.

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