query_search_analytics

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

No annotations are present, so the description carries the full burden. It implies a read operation ('Query') but does not state safety properties, idempotency, rate limits, or lack of side effects. More behavioral context is needed.

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 reasonably concise with a clear Args structure, but it could be more front-loaded to provide a quick summary before the parameter list. Every sentence is earned, but overall length is acceptable.

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?

Without an output schema, the description omits what the tool returns (e.g., clicks, impressions, aggregated data). It also lacks information on error handling, pagination, or data volume expectations, making it incomplete for a query 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?

The parameter descriptions in Args add significant meaning beyond the raw schema, explaining format (e.g., 'YYYY-MM-DD'), options (e.g., dimensions list), and constraints (row_limit max 25000). However, there is a slight inconsistency with the schema default for row_limit.

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 clearly states the verb-resource pair 'Query Search Console analytics data for a site,' indicating both the action and the specific data source. However, it does not explicitly differentiate from sibling tools like compare_time_periods or get_search_trends, which might also involve analytics data.

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?

No guidance is provided on when to use this tool versus the alternatives. The description only details parameters without suggesting context or prerequisites, leaving the agent without decision cues.

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