Search Console moves

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

Annotations already declare read-only, idempotent, open-world and non-destructive behavior, so the description's 'Read only' line is redundant. However, it adds a meaningful behavioral rule beyond annotations: a key absent from one period is counted as a full loss or full gain, which materially affects interpretation.

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 definition is front-loaded and efficient: it names the report first, then explains comparison periods and output fields. The only minor waste is 'Read only', which repeats an annotation.

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?

There is no output schema, and the description does a good job explaining returned fields: clicks, impressions, CTR, position for both periods, totals, and both date ranges. It also covers the key behavioral quirk for missing keys, making the definition complete enough to invoke and interpret correctly.

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 all five parameters are already documented, including the date windows, limit, site/client context and dimension enum. The description reinforces the N-days-against-N-days comparison but adds little parameter meaning beyond 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 clearly states a specific verb and resource: it returns Search Console week-over-week movers in queries or pages, with loss/gain framing. It does not explicitly differentiate itself from nearby GSC siblings such as gsc_performance or gsc_opportunities, so it falls short of a 5.

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 intended use is strongly implied by 'week-over-week moves' and 'lost and gained the most clicks', but there is no explicit when-to-use guidance and no named alternatives. An agent can infer this is for mover analysis rather than general performance reporting, but must still decide among GSC tools itself.

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