Wait For Message

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds real context beyond that: the blocking duration, the two possible outcomes (matching message with attachment metadata vs. 'no_message'), and the implied retry pattern. It does not mention any rate limits or how default filters (e.g., omit 'after') affect the wait window, which the schema only partly covers.

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 sentences, front-loaded with the purpose and the outcome shapes, with no filler. 'Wait briefly' and 'polls for up to 25 seconds' overlap slightly, and the total duration is stated twice across description and schema, but the redundancy is minor.

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?

With nine all-optional, fully documented parameters, an output schema handling return values, and annotations covering safety, the description only needs to convey the blocking semantics and the two outcomes. It does that, so an agent knows what to expect and what to do on an empty result.

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 each of the nine parameters already has documented meaning, including the 'after' default and the 25-second cap. The description adds no filter-specific guidance (e.g., how combining 'q', 'subject', and 'keyword' behaves), so it stays at the baseline.

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 names a specific verb and resource ('wait briefly for new mail') and states the mechanism (polling up to 25 seconds), so an agent can distinguish it from plain read tools like mailbox_list_messages. It stops short of naming any sibling tool explicitly, so it is clear but not fully differentiated.

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?

It gives positive usage context ('instead of manual polling') and explains the follow-up loop after a 'no_message' result ('so you can call again'). It does not state when NOT to use it (e.g., prefer a direct read when the message already exists), so exclusions are absent.

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