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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered; the description adds the concrete polling contract the annotations cannot convey: it returns timed_out: true after a 45-second wait and the caller should call again. That timeout and retry semantics are the key behavior an agent needs. It stops short of saying how many retries are sensible or what non-timeout payload fields look like.

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?

Two sentences, no padding, and the timeout instruction is placed usefully. However, the first sentence is dense with cross-tool jargon ('wait_for_run's contract, answering with get_review's payload') that takes a careful read to unpack, and the payoff statement is buried mid-sentence rather than front-loaded.

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?

There is no output schema, but the description compensates by naming the payload source (get_review) and the one sentinel field (timed_out) the caller must branch on, plus the 45-second duration that determines retry behavior. Given three fully documented parameters and annotations carrying the read-only profile, this is nearly complete; only retry guidance and the timeout payload's other fields are left implicit.

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 team, run_id and compare_to are already fully documented, including the '#332' run-number form and the compare_to cross-reference to get_review. The description adds no parameter meaning beyond that, which is acceptable at full coverage but earns only the baseline.

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 states the tool's outcome concretely: it waits for a run to finish and answers with get_review's payload, framed as 'the one call for check this deploy and give me something I can work from'. It is defined by reference to two siblings (wait_for_run's contract, get_review's payload), which is understandable but forces the agent to already know those contracts rather than stating the return content outright.

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 routes explicitly, positioning itself as the single call that replaces the wait_for_run-then-get_review sequence, which is real when-to-use guidance against siblings. It does not say when the agent should prefer get_review alone (e.g. if the run is already finished) or how long to keep re-calling before giving up.

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