Query search analytics

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses two genuinely useful traits: output ordering ('rows are sorted by clicks') and pre-flight validation ('invalid combinations are rejected with an explanation before Google is called'), which tells the agent bad calls fail cheaply. It says nothing about quotas or rate limits, but the safety profile is otherwise covered by 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?

Four sentences, front-loaded with what the call returns, and every sentence carries content (metrics, sort order, validation behaviour, sibling routing). The closing sentence about 'the matching query_*_analytics tool' is slightly abstract and could name the tools more directly, but there is no filler.

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 100% schema coverage, the description needs only to frame purpose and edge behaviour, which it does (sorting, rejected combinations, surface routing). The remaining gap is that dimension/aggregation constraints are left entirely to the schema rather than reinforced, which is acceptable but leaves the description thin for a ten-parameter tool.

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 100%, so the schema already documents all ten parameters in detail, including dimension combinations and search_type constraints. The description only summarises 'grouped by dimensions and filtered' and the default sort, so it adds little beyond the structured fields; baseline 3 applies.

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 names the exact resource (the Performance report) and the metrics it returns (clicks, impressions, CTR, average position), plus the grouping/filtering operation. The final sentence routes the agent away from the query_*_analytics siblings for Discover/Images/video/News surfaces, so an agent can tell which tool applies without opening a schema.

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?

It explicitly states when to pick a sibling instead: for Discover, Images, video, Google News or the News tab, use the matching query_*_analytics tool. It gives no guidance against the other query variants (query_hourly_analytics, compare_periods, explain_change, query_search_appearance), so the routing is clear but not exhaustive.

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