dsh_wait

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

No annotations are provided, so the description carries the full behavioral burden and does so well: it discloses the 50 s server-imposed wait cap and why it exists (to stay under the client's tool timeout), the exact partial-failure shape (timed_out: true with only the state field), the retry contract, the no-progress-summary expectation, and that progress notifications are emitted only when the client requests them. These are operational traits an agent cannot get from the schema.

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?

Front-loaded with the core action and return value, then layered with the alternative-mechanism advice and the timeout/retry contract; every sentence carries information. It is somewhat dense with parenthetical asides, which slightly costs readability, but there is no filler.

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?

With no output schema and no annotations, the description covers the return contract itself ('final status and reply', plus the timed_out variant), the timeout and retry behavior, and the interaction with the sibling dsh_send. Nothing an agent needs to call this correctly and interpret the result is missing.

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?

There is a single parameter with 100% schema description coverage ('Run id from dsh_send'), so the schema already does the heavy lifting. The description adds one useful nuance beyond it: the same run_id is reused across repeated calls in the timed_out retry loop, which tells the agent the id is stable across invocations.

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 verb and resource ('Wait for a run to finish') plus the return payload ('final status and reply'), which is exactly what an agent needs to decide between this and siblings like dsh_status or dsh_list_runs. It also explicitly names the competing mechanism (background wait_command in dsh_send), so it is distinguishable without opening any 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?

Gives an explicit preference rule with its precondition: use dsh_send's background wait_command 'when your client can run background shell commands and wake you when they exit', because it costs no turns. It also states the follow-up protocol for the timed_out case (call dsh_wait again with the same run_id, without summarising progress), which is when-to-use guidance for the retry path.

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