query_search_analytics

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: a two-to-three-day data finalization lag that explains short-looking recent windows, and Google's privacy withholding of rare queries causing query-level clicks to sum to less than site totals. These are non-obvious data behaviors that directly affect interpretation of results, going beyond annotation defaults.

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 description is compact yet information-dense: a one-sentence definition, a one-sentence routing to alternatives, and a marker introducing two critical caveats. Every sentence earns its place, and the most important identifier (what the tool is) is front-loaded. No fluff 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?

Given the tool's complexity (eleven parameters, many dimensions) and lack of an output schema, the description provides key interpretive context (data lag, privacy aggregation) that an agent must know to correctly evaluate results. It does not explicitly describe the return structure, but that is largely standard. The missing piece is a brief note on pagination or default row behavior, though schema already covers row_limit and start_row. Overall it is nearly 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 description coverage is 91%, so the input schema already documents parameters thoroughly, including site format, enum meanings, date formats, and default values. The description does not add per-parameter semantics but rather focuses on overall tool behavior. Per the baseline rule for high schema coverage, a score of 3 is appropriate; it adds marginal value by mentioning dimension combinability but not new parameter detail.

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 the specific verb 'report' and enumerates the exact metrics (clicks, impressions, CTR, average position) and the resource (Google Search), with a clear grouping capability. It explicitly contrasts itself with sibling tools like top_queries and top_pages, distinguishing 'full-control' from convenient one-call alternatives. This leaves no ambiguity about what the tool does.

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 states a clear use case: the core report for custom dimension combinations, and explicitly advises that for common user questions, top_queries, top_pages, striking_distance, and compare_periods are one-call alternatives instead of assembling a body manually. This gives agents a routing rule. However, it does not explicitly say 'when not to use' beyond that implied contrast, so a small gap remains.

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