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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, yet the description still adds real behavioral context: a hard 30-second cap shared with a per-caller wait limit, a per-source cursor model, and the return shape (events with cursors, or timedOut). It also flags environment constraints (SMS needs an active phone add-on; phones=false on this server; SMS stays readable during provider outages) that annotations cannot express.

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 capability and return contract are front-loaded and dense with useful detail, but the tail end drifts into environment trivia ('This server reports phones=false; scheduled job sources are enabled') and terse jargon ('Expired/denied approval is never permission') that costs reading effort without clear payoff.

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 read-only polling tool with no output schema, the description covers what matters: the wait window, the multiplexed source model, cursor semantics and the timeout return value. Gaps remain on event payload shape, ordering across sources, and whether consumed events are re-returned on a subsequent wait with the same cursor.

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?

With schema description coverage reported at 0%, the description partly compensates by enumerating the per-source shape (kind, id, optional token, after cursor) and noting the 1–10 source bound. However, it says nothing about timeoutSeconds beyond the 30-second ceiling already encoded as a schema maximum, and does not explain the default wait behavior or what happens when a source yields no events.

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 first sentence gives a specific verb and resource: wait once for any of 1–10 sources spanning webhook, email, approval, job and SMS kinds. The multiplexed scope implicitly distinguishes it from the single-kind siblings (wait_for_webhook, wait_for_email, wait_for_sms, wait_for_approval), but it never names those siblings to make the distinction explicit.

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?

Usage rules are scattered rather than front-loaded: check /api/capabilities phones before creating a phone number, email events exclude sent mail, and an expired/denied approval is never permission. There is no explicit statement of when to pick this multi-source wait over the single-kind wait tools, so the selection guidance is implied rather than stated.

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