cs_agent_wait_many

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

Beyond the read-only and idempotent annotations, the description reveals meaningful behaviors: mode 'any' returns all currently ready items, mode 'all' returns early on permissions or timeout, and interrupted all-waits require manual accumulation via pendingTurnIds. These details are not present in the schema and materially shape correct usage.

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?

Three sentences, front-loaded with the primary action, then mode details, then recovery guidance. No redundant words; every clause contributes to either understanding or usage. The structure flows logically from what to do, to mode behavior, to post-interruption handling.

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 polling utility with 3 parameters and no output schema, the description covers the essential workflow: issuing turns first, choosing modes, handling partial results, and resuming. It does not specify the exact return value format, but the description of 'ready items by turnId' gives adequate shape. Overall, sufficient for an AI agent to invoke correctly.

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 baseline is 3. The description adds semantic nuance to the 'mode' parameter by clarifying that 'any' returns all ready items, not just one, and introduces the concept of pendingTurnIds for handling interruptions—valuable context beyond the schema's terse 'returns when at least one turn is ready.'

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 opens with a specific verb+resource: 'Wait for multiple turns,' distinguishing from sibling cs_agent_wait_turn. It immediately establishes the tool's role ('after you send all independent turns first') and elaborates mode semantics, leaving no ambiguity about its purpose.

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 usage instructions: send independent turns first, then choose mode based on whether you want current ready items or to wait for all terminal. It also advises how to recover from interrupted 'all' waits by accumulating ready items and continuing with pendingTurnIds. Fails to explicitly name alternatives like cs_agent_wait_turn, but the context makes the distinction clear.

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