site_snapshot

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

No annotations are provided, so the description must cover behavioral traits. It states the tool returns aggregated totals for a current period versus a prior period, and warns against extrapolation. However, it does not disclose whether the data accounts for any filtering (e.g., device, country), how the prior period is calculated, or any limitations like data freshness or sampling. The warning about not speculating adds some transparency, but overall more detail would be beneficial.

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 extremely concise: two sentences, each serving a purpose. The first sentence states the function clearly, and the second provides critical usage instructions. No unnecessary words, and the key information is front-loaded.

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 2 parameters, no output schema, and sibling tools that also provide performance data, the description is moderately complete. It names the metrics returned but not the structure (e.g., whether it's a single object or array). The tool's output is a simple aggregated comparison, so a detailed return format may not be critical, but the lack of explanation of the prior period's calculation leaves a gap.

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?

With 0% schema description coverage, the description must compensate. It mentions 'last N days' which implies the 'days' parameter, but does not explicitly define the 'site_url' parameter or clarify the format or constraints. The prior period is not explained (e.g., same length preceding period). The description adds minimal meaning beyond what the schema provides (parameter names and types).

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 tool provides aggregated totals (clicks, impressions, CTR, position) for the last N days compared to a prior period. It identifies the resource (site's performance data) and the action (aggregation and comparison). While it does not explicitly distinguish from sibling tools like search_analytics, the focus on aggregated totals vs prior period makes its purpose reasonably distinct.

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 description provides important usage guidance on not speculating beyond the returned data and citing site_url and date_range when reporting. However, it lacks guidance on when to use this tool versus alternative tools (e.g., search_analytics for granular data, or cannibalization for specific insights). There is no mention of prerequisites or context where this tool is preferred.

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