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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real context the annotations do not: terminal states (ready/failed/unavailable/expired), the retry_after_seconds backoff contract, and the important fact that research_prepare_cohorts does not return a job_id. It does not mention rate limits or how long results persist, keeping it short of a 5.

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?

Structure is strong: the precondition is front-loaded, then Selection/Presentation/Evidence sections each carry distinct guidance. A few clauses are dense and slightly awkward ('Do not imply a preparation default answers the requested comparison'), which costs it a point, but there is little true filler.

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 one required parameter, an output schema present, and rich annotations, the description covers everything an agent needs: where the job_id comes from, when not to call, when to stop polling, and which tool to call next with the returned snapshot_id.

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% and the job_id property already documents the 64-hex format and the snapshot_id distinction. The description reinforces this with 'Pass that exact job_id' and sources the value ('from an earlier response'), adding marginal but useful invocation guidance rather than new syntax.

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 makes clear this tool polls/reports on an existing cohort preparation job ('Stop polling on ready, failed, unavailable or expired results') and explicitly separates it from research_prepare_cohorts, which starts one. The verb ('check status') is implied by the title and the polling language rather than stated outright, so it is slightly indirect, but the resource and scope are unambiguous.

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?

It names the precondition (job_id already known from an earlier response), three explicit exclusions ('starting a cohort preparation, refreshing a ready comparison, or rapid/unbounded polling'), and the sibling to use for the follow-up step (research_compare_cohorts). Stop conditions and retry_after_seconds handling are also specified.

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