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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the marginal contribution is the data-shape caveat: both windows are N calendar days in the property's time zone, they do not overlap, and the current window ends today while today is still filling in. That partial-day warning is exactly the kind of gotcha annotations cannot express and that would otherwise cause an agent to misread a low days=1 diff. It stops short of noting row caps or response shape, but an output schema exists to cover the latter.

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?

Three short sentences, leading with the one-line definition before the mechanics and the caveat. The parenthetical example (days=1 is today vs yesterday) is the most valuable sentence and is not padded with restated parameter names.

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?

For a 5-parameter, 1-required tool with a full schema, complete parameter descriptions, an output schema, and read-only annotations, the description supplies the one thing structured fields cannot: the time-zone/non-overlap/partial-day-window behavior. It could go further by distinguishing itself from `compare_periods` or noting row-limit behavior, but nothing needed to invoke 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?

Schema coverage is 100%, so the baseline would be 3; the description earns the bump by explaining the semantics the schema only gestures at — the windows are calendar days in the property's time zone, non-overlapping, and anchored to today, which explains why days=1 compares today against yesterday rather than two completed days. It adds no guidance on `limit` or `by_dimension`, but those are fully described in 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?

"Diff the last N days vs the prior N days" gives a specific verb (diff) and resource (the two adjacent windows of GA4 data), and the WoW/MoM phrasing tells an agent the intended granularity. It does not differentiate from the sibling `compare_periods`, which sounds near-identical, so an agent cannot resolve GA4-vs-other-source selection from the description alone.

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 implied rather than stated: the WoW/MoM/day-over-day framing signals when a period comparison is the right tool, but there is no explicit "use this instead of ga4_overview when..." routing and no exclusion against the sibling `compare_periods`. The agent must infer usage from examples.

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