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

The description adds substantial behavior beyond annotations: it discloses the terminal states, the timeout return value, and the idempotent retry pattern ('call again'). This aligns with annotations like idempotentHint=true and readOnlyHint=true without contradicting them. The retry instruction is especially valuable for an agent deciding how to handle a timeout.

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 concise sentences with no filler. The main action and terminal states are front-loaded, and the timeout/retry instruction is placed immediately after. Every clause earns its place and no redundant information is included.

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?

The description is sufficient for an agent to invoke the tool correctly: it states what it waits for, what the possible settle states are, what happens on timeout, and how to retry. The output schema and annotations cover return shape and safety, so no critical context is missing. The only minor ambiguity around 'final reply' in the needs_input case is not enough to lower the score.

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?

The schema already covers both parameters fully: run_id is described as a trun_... id, and timeout_seconds has default, max, and behavior notes. The description mentions 'when the timeout passes' but adds no parameter-level meaning beyond the schema. With 100% schema description coverage, the baseline of 3 is appropriate.

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 a specific verb and resource: 'Wait for a run to settle' and returns it with the agent's final reply. It clearly enumerates the terminal conditions (completed, failed, or needs_input), which makes the operation unambiguous. It doesn't explicitly name sibling alternatives like get_run, but the waiting semantics distinguish it from simple status retrieval.

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?

The description gives clear context for when to call the tool: when you need to block until a run settles. It also provides explicit retry guidance: 'Returns wait_timed_out if it is still running when the timeout passes; call again.' It does not discuss alternatives or exclusions, but the primary usage and retry behavior are well covered.

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