Query Search Console performance data

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

Annotations already carry readOnlyHint, idempotentHint, and openWorldHint, and the description reinforces this with 'Read-only.' Beyond that, it discloses important behaviors the annotations cannot convey: data lags 2-3 days, dataState='all' surfaces fresh partial data, the default 25-row cap versus the API's 25,000 limit, the explicit warning not to assume full results, and offset-based paging. This is substantial behavioral context added on top of the annotations.

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?

Every sentence earns its place: purpose first, then the primary-tool designation, then prerequisites, date constraint, lag/freshness, row-limit warning, paging, and a closing 'Read-only.' The most critical constraints (exact siteUrl, date format) are front-loaded. No filler or repetition of schema 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?

For a complex 10-parameter tool with no output schema, the description covers the essentials well: it states return metrics, grouping behavior, prerequisites, date format, data lag, and pagination limits. The only notable gap is the precise response row structure (how grouped results are keyed/serialized), which the description only hints at via 'grouped by the dimensions you choose'. Given the absent output schema and tool complexity, slightly more return-format detail would make it fully complete.

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 100% and the schema itself is unusually rich (each parameter has meaningful prose, e.g., limit's 'protect the context window' and startRow's 'offset, not a page token'). On the baseline-3 for full coverage, the description adds genuine semantic linkage: it connects dataState to the data-lag problem and reframes limit as a truncation risk that agents must deliberately raise. This goes slightly beyond what the schema states.

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 verb ('Returns'), a specific resource (Search Console performance data), and the exact metrics returned (clicks, impressions, CTR, average position). It distinguishes itself from the GA4 siblings by noting relative dates are unsupported 'unlike the GA4 tools' and declares itself 'the primary SEO analysis tool', clearly differentiating it from the ga4_run_report and gsc_compare_periods siblings.

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 strong contextual guidance: it declares itself the primary SEO tool, requires siteUrl to come from gsc_list_sites, warns that relative date forms are not supported (unlike GA4), and instructs to page with startRow and raise limit deliberately. However, it never explicitly states which sibling to use instead in any given scenario (e.g., when to prefer gsc_compare_periods or ga4_run_report), so the when-not-to-use routing is left implicit.

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