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

Annotations only declare readOnly/openWorld safety, so the description carries the semantic burden and does: it discloses that a session is counted once per page visited, that rows sum to more than total sessions, and that activeUsers repeat across rows. This is precisely the non-obvious behavior that would otherwise cause an agent to misreport metrics.

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?

Front-loads the core definition, then layers the double-counting caveat and the two sibling alternatives. Every sentence adds decision-relevant information; nothing is restated from the schema or annotations.

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?

An output schema exists, yet the description still names the returned metrics and warns about their cross-row duplication, which is the one thing the output schema cannot convey. Combined with aggregation advice and the GSC alternative, nothing needed to call or interpret this 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?

Schema description coverage is 100%, so days/limit/property_id are already documented with ranges and defaults. The description only echoes 'over the last N days' without adding format or interpretation guidance, so it neither compensates nor adds much 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?

Names a specific verb and resource ('Top pages by sessions over the last N days (GA4 pagePath)') and immediately corrects the misleading title by stating 'These are not landing pages'. An agent can distinguish this from ga4_overview or correlate_gsc_to_ga4 without opening any schema.

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?

Gives explicit routing rules: 'Take totals from ga4_overview' and 'To compare pages with Search Console clicks, use correlate_gsc_to_ga4'. It also states the condition that makes this tool wrong for landing-page questions, which is exactly the disambiguation an agent needs.

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