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

Despite readOnlyHint=true being declared, the description adds substantial behavioral nuance: the different denominator for scroll_depth, null handling when no depth signal exists, ROAS null on Path A, and the expected lower previous value for period='today'. These are exactly the kind of edge cases that prevent misuse and are not derivable from annotations alone.

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 long but every sentence adds necessary detail for correct invocation, given the tool's complexity. It front-loads the primary return payload, then progressively covers edge cases and parameter semantics in a logical order. No redundant or filler sentences were found.

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?

The description covers all operational aspects: what is returned, how each metric is computed, null/edge-case behavior, parameter scoping, period semantics, and cross-tool consistency. With an output schema present, it appropriately focuses on behavior rather than return structure, and nothing an agent needs to call it correctly is missing.

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 carries the full burden for all four parameters. It explains the meaning and valid values for country (ISO2), device (enum with examples), period (default 30d, accepted strings and integer range), and site_id (optional with OAuth fallback). This goes well beyond the schema's structural definitions.

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 opens with a precise statement of what the tool returns — the full headline summary for a site and period — and enumerates the exact KPIs, trends, and ad-spend fields. It clearly distinguishes itself from siblings by naming specific outputs (e.g., ROAS definition, engagement metrics) that other tools like get_breakdown or get_page_trend would not provide in one call.

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?

Explicitly instructs to call this tool first when a user asks 'how is my site doing?', giving a clear trigger. It also explains when the tool's behavior changes (e.g., period='today' comparison, ROAS null cases) and references get_channel_breakdown for consistency. However, it does not explicitly contrast with alternatives like 'use get_breakdown for per-channel details', so the when-not-to-use guidance is implicit rather than explicit.

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