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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: exactly which figures are all-time versus a 30-day window, that aiVisits.likely is inferred rather than counted, and how sampling is reported (visitor counts plus a 95% Wilson interval, and deliberately no interval on visitorQualityLift because a ratio of rates is not a proportion). This is the kind of interpretation guidance that prevents analytic misuse.

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?

Content is front-loaded with the resource summary, and nearly every clause carries meaning, but the body is a dense semicolon-chained wall of field-level specification that is hard to scan. The sampling/z-test rationale is legitimately needed given no output schema, yet the lack of any structural breaks costs readability.

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 no output schema, the description carries the full burden of explaining return values, and it does name the key fields, their windows, and their sample structures. Remaining gaps are modest: no error behavior, no note on auth failures beyond the schema, and no mention of sibling reports that overlap in subject matter.

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?

There is a single parameter at 100% schema description coverage, and the schema already spells out the connected-app versus API-key requirements and the select_site interaction. The description adds nothing about siteId, so it neither compensates nor detracts — baseline 3 applies.

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 specific resource definition — attributed visits, verified revenue by currency and source, unverified conversions kept separate — so an agent knows exactly what data comes back. It also anchors the tool to REST /v1/sites/{siteId}/metrics. It stops short of naming any sibling (e.g. get_sources_report, get_visibility_score) to differentiate scope, so it is clear but not sibling-routing.

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 only implied: this is the metrics tool, and the guidance given is about consuming output ("Never add or divide figures from different windows"), not about when to pick this over another tool. No alternative tool is named and no precondition such as needing select_site first is stated here, even though the schema hints at it.

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