wait_any

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

With annotations already covering the safety profile (readOnly/idempotent/non-destructive), the description still adds substantial non-obvious behavior: same-poll tie resolution by list order, the right-padding caveat that breaks end-anchored patterns, and the fact that timeout is not an error but an ok=true/index=-1 return. It also discloses the special detect_child_exit path where a dead child short-circuits the wait.

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-loads the core purpose and the example before detailing tie-breaks and return shape, so an agent can stop reading early. It is fairly dense and slightly long, but nearly every clause conveys a distinct behavioral fact (padding, tie order, timeout-as-success, child exit) rather than restating the name.

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?

No output schema exists, yet the description spells out the full return object ({ok, index, matched, alive, exited, text, json}) including the sentinel values for timeout and child-exit cases. Combined with the patterns/timeout semantics, an agent has everything needed to call it and interpret both success and timeout outcomes.

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 0%, so the description carries the param burden and largely does: it defines `patterns` scan order and matching semantics, and explains `timeout_ms` behavior (returns ok=true with index=-1 rather than erroring, or returning at once on child exit). Only `sid` goes unexplained, which is a minor omission against the strong coverage of the other two.

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 ANY of `patterns` to appear on screen, explicitly framed as pexpect expect([...]) semantics. It doesn't name its closest siblings (wait_regex, wait_ready, wait_change), so an agent must infer the distinction from the 'race several possible outcomes' framing rather than an explicit contrast.

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 a concrete usage scenario ('race several possible outcomes at once — e.g. patterns=[">>> ", "Error", "Password:"]') and guidance on ordering ('put the most specific first'), which tells the agent when this tool fits. It stops short of stating when NOT to use it versus wait_regex or the other wait_* siblings, so no alternative is explicitly routed away.

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