Wait for a subagent invocation

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

Annotations already mark this as readOnly, idempotent, and non-destructive. The description adds stateful behavior beyond annotations: a running response leaves the invocation active and that wait_agent may be called multiple times. It also clarifies that cancellation is handled by a separate sibling, not by this tool.

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 short paragraphs, with the core purpose in the first sentence and operational guidance in the second paragraph. Every sentence adds information; no filler or redundancy.

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 covers the key operational distinction (running vs. final result) and what to do in each case, plus the explicit pointer to cancel_agent. With an output schema present, it doesn't need to detail the return structure, and the timeout semantics are reasonably implied by the running-snapshot outcome.

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 the baseline is 3. The description does not add any parameter-level meaning beyond the schema, but the schema already documents invocation_id and wait_timeout_seconds clearly, including defaults and bounds.

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 clear verb-resource pairing ('Wait briefly for one invocation') and the expected outcome ('return either a running snapshot or its final result'). It distinguishes itself from cancel_agent by explicitly naming the cancellation path, and from start_agent by position (waiting follows starting).

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?

Provides explicit guidance on how to respond to a running result: 'call wait_agent again later.' It also delineates the boundary with cancel_agent: 'Use cancel_agent only when the invocation should be stopped.' This is sufficient for an agent to decide between polling and cancelling.

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