Wait for a job (bounded polling)

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

With no annotations, the description carries the full burden and does well: it discloses the polling cadence, the timeout bounds, the rationale for the 55s max (MCP client 60s cut), the repeat-call loop behavior, and progress notifications. It stops short of describing timeout/error outcomes or auth requirements.

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 dense sentences, no filler, with the core polling contract front-loaded before the retry guidance and per-model timing. Every clause earns its place.

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, so the description must convey return semantics; it does by explaining the state='running' vs terminal distinction and the progress notifications. Coverage is good, with minor gaps around timeout exhaustion and error returns.

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 only 33% (only timeout_s is documented in the schema), but the description compensates by restating the timeout default/max and, more valuably, attaching concrete runtime expectations to each model enum value. The id parameter remains unexplained but is self-evident.

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 behavior: polls a job's status on an interval and returns as soon as it reaches a terminal state, with a bounded timeout. This clearly reads as the 'wait until done' counterpart to get_job_status/get_job_result, though it never names those siblings 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?

Explicitly tells the agent what to do when state='running' (call it again) and provides per-model expected durations so the agent can judge feasibility. It does not explicitly contrast with get_job_status for a one-shot check, which is the only real gap.

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