raid_wait_turn

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

With no annotations, the description fully bears the responsibility for behavioral transparency. It thoroughly explains the timeout behavior via max_seconds, lists all possible return outcomes (turn text, game over, error, no turn yet), and even directs the agent on how to handle the returned prompt. This gives a complete picture of what to expect without hidden side effects.

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 description is compact and well-structured, packing all essential information into a single paragraph. It lists return values in order, explains the timeout, and gives a clear instruction for the agent. There is no redundant fluff; each sentence serves a distinct purpose.

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?

Although an output schema exists, the description goes beyond it by explaining the semantic meaning of each possible return string and providing contextual instructions for the agent (show to human, wait for choice). This makes the tool completely understandable in its intended use case without needing to consult external references or infer behavior.

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?

The only parameter, max_seconds, has no description in the schema. The tool description compensates by explaining that it bounds the wait time and provides a default of 30 seconds. This gives the agent sufficient understanding of the parameter's purpose and units, even though the schema itself is silent.

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 clearly states the tool's purpose: waiting for the next turn's prompt. It specifies the action (wait) and the resource (turn prompt), and it distinguishes itself from sibling tools like raid_play or raid_say by focusing on the waiting step. The return values are enumerated, making the purpose unambiguous.

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 provides clear guidance on when to use this tool: it should be called to wait for a turn, and if 'No turn yet' is returned, it can be called again. It also instructs the agent to show the result to the human and wait for their choice before calling raid_play. However, it does not explicitly contrast with alternatives like raid_status or raid_poll_chat, so it falls short of fully explicit when-not-to-use guidance.

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