Wait until a subagent needs attention

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

No annotations are provided, so the description carries the full burden — and it delivers richly: five wake modes (done/permission/report/stopped/dead/timeout), report-once delivery even if arrived before the call, background-task vs. blocking execution depending on host MCP-task support, and timeout returning a live-state snapshot. This goes well beyond annotation-level disclosure.

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?

The core purpose is front-loaded in the first sentence, and the remaining three sentences pack in essential behavioral detail with no filler. It is dense — the em-dash clauses are heavy — but every clause earns its place for a blocking tool whose wake semantics are the entire contract.

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?

For a complex tool with no output schema and no annotations, the description covers wake modes, timeout behavior, report-delivery semantics, host-dependent execution, and the permission-tool routing. The only gap is that it never specifies the exact returned payload shape for each wake mode, which an agent would need since there is no output schema to fall back on.

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%, so the baseline is 3; both name and timeout_ms are already documented with defaults and bounds. The description adds some value beyond the schema by explaining what a timeout produces ('snapshot shows live state') and what a permission wake means, but it does not materially extend the parameter semantics.

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 opening clause 'Block until the subagent needs you, then return what happened' names a specific verb ('block'), resource (the subagent), and outcome. It differentiates from the sibling 'poll' by emphasizing blocking semantics and the immediate-return behavior for already-attention states, so an agent can tell them apart without opening the schema.

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 behavioral context: it enumerates when to use it (blocking for attention) and states that already-attention states return immediately 'so it doubles as is it done?'. It also routes permission wake-ups to the permission tool. However, it never explicitly names poll as the non-blocking alternative or states when not to use wait, leaving that contrast implicit.

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