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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond, disclosing the 2–3 day data lag, that anonymized queries are dropped from results (and dropped entirely under a query filter), the 500-row hard cap and offset-based paging loop, and a full error contract (missing_permission/not_found/rate_limited/auth_error/http_error returned as a dict with message and hint). That is exactly the operational context an agent needs and cannot get from structured fields.

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?

Front-loading is excellent: the high-cost mistake (omitting dimensions yields ['query'] rows, not a total) is stated twice, early and in caps, before anything else. The text is long but nearly every sentence conveys an operational rule. Minor waste exists in restating the aggregation advice at the end and in some repetition between the opening totals guidance and the closing sentence.

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?

Nine parameters, zero schema descriptions, and no enums in the schema, yet the description covers every parameter, the date-precedence rule, the filter grammar, the paging loop, and the error surface. With an output schema present, return-value structure is correctly left to the schema rather than duplicated. Nothing an agent needs to call this correctly is missing.

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 entire burden and does so: it defines days semantics (ending today minus 3), date format and the both-or-neither rule plus the specific invalid_date_range error, the dimension_filter dict shape with the full operator enum (including RE2 regex), country format as ISO-3166-1-alpha-3 like 'aut', device case convention, search_type enum with its error code, and limit/start_row interaction. Practical examples are given for the trickiest parameter.

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 opening names a concrete resource and output shape: a Search Analytics report with an enumerated set of dimensions (query, page, country, device, searchAppearance, date). An agent immediately knows this returns Search Console performance data. What's missing is any explicit demarcation from close siblings like sc_top_queries or sc_top_pages, so the agent must infer that this is the general/customizable counterpart.

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?

Very strong internal guidance: it tells you to use dimensions=[] for property-level totals (with a concrete example question about clicks in the last 28 days), dimensions=['date'] for a daily trend, and warns that query-level sums undercount. It also explains when start_date/end_date supersede days. It stops short of naming an alternative sibling tool or stating when not to call this (e.g. 'use sc_top_pages for a simple top-pages list').

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