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

Annotations only declare readOnlyHint=false, idempotent=true, destructive=false; the description adds the details that actually drive agent behaviour — the call blocks briefly and re-issues the same request, no job id is surfaced, progress is not an answer, and the snapshot_id must be retained. This is consistent with idempotentHint=true and with a non-readOnly call that materialises server-side state.

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-loaded with the triggering condition and organised under Selection/Presentation/Evidence labels, so an agent can scan it. It is dense and slightly repetitive around progress/retry ('Progress is not an answer' followed by 'If history is still warming, retry'), but nearly every clause carries operational weight.

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, so return values need not be spelled out, yet the description still tells the agent what matters in the response (facts.summary, per-group return_pct/relative_pp/as_of, charted/member counts) and when not to drill into /initial/catalogue, /initial/selection or /initial/history_range. For a single-enum-parameter preparation tool with annotations and an output schema, nothing needed 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 one parameter at 100% schema coverage and an enum already documenting 1/7/30 with a default, the description's 'days selects 1, 7 or 30 days of retained history' largely restates the schema. The added nuance — reuse a suitable snapshot instead of re-preparing on each refinement — is about behaviour rather than the parameter, and the mention of resolving group IDs from the catalogue refers to no parameter in this schema, so it does not sharpen parameter meaning.

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?

States a specific action (prepare retained cohort-comparison history) and grounds it with a concrete example (DeFi vs AI tokens over seven days), which removes ambiguity about what the tool produces. It distinguishes itself functionally from siblings by rejecting taxonomy lookup and progress-handle waiting, though it never names research_discover, research_cohort_status, or research_compare_cohorts explicitly.

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?

Explicit when-to-use ('starting a group relationship comparison without a usable prepared snapshot'), explicit when-not (taxonomy lookup alone, waiting on a progress handle, re-preparing per filter change or replay frame), plus a retry protocol when history is still warming. The reuse instruction ('retain snapshot_id', answer from facts.summary rather than re-running) closes the loop on follow-up behaviour.

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