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

Annotations already flag read-only, idempotent, non-destructive, so the safety profile is covered. The description adds real context beyond that: comparison fields emitted, the rule that keys present in only one period show zeros, the Search Console ~3-day lag and that the period is echoed in every response, and that branded sorting throws invalid_argument unless branded terms are configured. It does not mention pagination or row ordering stability, but this is well above the annotation baseline.

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?

It is front-loaded with the resource and the returned metrics before the sort rules, and the bilingual tail is brief. The dense enumeration of prev*/change keys is long but earns its place because there is no output schema; a slightly tighter phrasing would help.

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 14-parameter read tool with no output schema, the description covers the return shape, comparison modes, default date window behavior and sort semantics. Remaining gaps are minor — no guidance on limit relative to result cardinality, and no mention of how device rows interact with other filters.

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%, so baseline is 3, but the description adds meaning the schema does not: sort values growth and decline are defined as largest click gain/loss vs comparison, position sorts lowest-first, and minImpressions is tied to a noise-reduction recommendation for ctr/position. That is real semantic value on top of the schema.

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 opens with a specific resource and scope: device breakdown (MOBILE, DESKTOP, TABLET) for one property over a period, and enumerates the returned metrics. It is clear what the tool does, though it never names the sibling breakdown tools (query_countries, breakdown_by_path, get_breakdown) that an agent would need to distinguish it from.

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?

There is one concrete usage rule — 'For ctr/position use minImpressions >= 20 to avoid noise' — which is genuinely actionable. However there is no guidance on when to pick this tool over the many sibling breakdown tools (query_countries, breakdown_by_path, query_top_pages); usage is only implied by the resource named.

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