dsh_wait

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

With no annotations, the description carries the behavioral burden and does meaningful work: it discloses a bounded wait (at most 30 seconds), frames the operation as observation, and warns that idle is not proof of success. It does not detail timeout behavior or return semantics, but the key behavioral risk is surfaced.

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 sentences, front-loaded with the primary action and time bound. Every clause earns its place: the wait behavior, the 30-second cap, and the necessary success-verification caveat.

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 enough to select the tool and understand the basic invocation, but without annotations or an output schema it leaves ambiguity around return values, timeout behavior, and how sessionId should be obtained or used. The review-history/files guidance helps, but a complete definition would clarify what happens when the 30 seconds elapse.

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 0%, and the description partially compensates by explaining the functional role of seconds as the idle-observation duration. However, it does not explain sessionId semantics or how it relates to the queue/job, and it omits optional/default behavior for seconds, leaving a clear gap.

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 clear, specific action: observe a queue/job for idle with a 30-second cap. It distinguishes itself from status/history siblings by emphasizing waiting rather than reporting, and it adds the important caveat that idle does not imply success. It does not explicitly name sibling tools, so it stops short of full differentiation.

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 practical context: wait for idle, then verify by reviewing history and files rather than trusting idle. It implies the alternative path to dsh_history/files, but it does not explicitly state when not to use this tool or name the sibling alternatives.

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