Compare two periods

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value beyond that: it defines the return shape and, crucially, the sign convention that a negative position change means improved ranking — a non-obvious detail an agent would otherwise misinterpret. It stops short of noting pagination or the effect of data_state on the comparison.

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?

Two sentences, front-loaded with the core purpose, followed by the one caveat an agent is most likely to get wrong. Every clause earns its place with 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, return values need not be explained, and the 12-parameter schema is 92% self-documenting. The description supplies the non-obvious semantic notes (equal-length windows, negative position change) that the schema cannot express, so it is complete enough for correct invocation.

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 92%, so the schema already documents nearly every parameter with defaults and enums. The description adds little parameter-level detail beyond the implied equal-length requirement for the current/previous windows, which is the baseline 3 case where the schema carries the load.

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 states a specific verb and resource — comparing search performance between two equal-length periods — and even sketches the output shape (totals plus per-key breakdown with absolute and percent changes). It is clear on its own, but it never names or contrasts against siblings like query_search_analytics or explain_change, so the agent must infer the boundary.

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?

Usage is implied by the framing (a period-over-period comparison) and the 'equal length' constraint hints at when it applies. However, there is no explicit when-to-use/when-not guidance and no routing to explain_change for single-change analysis or to query_search_analytics for a single period, leaving the agent to guess.

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