gsc_site_snapshot

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

With no annotations, the description carries the full burden. It explicitly instructs the agent to base analysis only on returned data, report exact numbers, avoid speculation, and admit insufficient information—providing strong behavioral context. It also mandates a rich interactive presentation format. It does not mention internal side effects, but 'returns' implies a read-only operation, and the presentation rules are clearly disclosed.

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 longer than average but well-structured into three sections: overview, IMPORTANT analysis rules, and PRESENTATION requirements. Each sentence adds value, with the purpose front-loaded. The length is justified by the need to convey both data handling rules and output formatting expectations.

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 simplicity (2 optional params, straightforward output) and no output schema, the description adequately covers return values (metrics list) and provides clear instructions for handling incomplete data. It lacks explicit edge-case behavior (e.g., empty dataset), but the 'say so clearly' instruction mitigates this. Overall, it is complete for its scope.

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 coverage is 100%, so the baseline is 3. The description does not add significant parameter detail beyond the schema; it references 'prior period' (implying 'days') but does not explain the 'dataset' parameter or how they interact. The schema already describes both parameters adequately, so no compensation is needed.

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 ('Get a quick overview') and resource ('how the site is performing'), and lists the exact metrics returned (clicks, impressions, CTR, position, unique pages, queries) plus the comparison to the prior period. This distinguishes it from the more specialized sibling tools like gsc_quick_wins or gsc_ctr_opportunities, which target specific aspects.

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 phrase 'quick overview' implies use for high-level summaries, and the mention of 'comparison to the prior period' gives context. However, there is no explicit guidance on when to choose this tool over alternatives like gsc_report or ga4_gsc_page_performance, nor any stated exclusions or prerequisites.

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