teams_wait_for_messages

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

With no annotations, the description carries the full burden and does well: it discloses that the call blocks up to wait_seconds, that 60 is the cap, that a scoped chat filter can yield an empty answer, and that seq is a resumable cursor. Missing are permission requirements and whether exceeding 60 errors or clamps.

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 dense sentences that front-load the core behavior and never pad. The final sentence is grammatically tangled ('other chats' messages are skipped and the answer may be empty before wait_seconds'), costing a point on clarity but not on length.

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 3-param, no-annotation, no-output-schema tool, this covers the essentials: what it returns (events and seq), how to resume, and the empty-result edge case. It falls short on default wait_seconds, cursor invalidation, and error behavior at the 60s cap.

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 only 33% — after_seq and wait_seconds have no schema descriptions at all. The description compensates partially by defining after_seq as a resume cursor (pass back the returned seq) and wait_seconds as a bounded wait, but it never explains the 'only this chat (title or id)' matching semantics and leaves wait_seconds' default unstated.

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?

Names a specific resource and behavior: new incoming messages, with a long-poll wait bound by wait_seconds (max 60). It's clearly a blocking/polling tool, distinct from teams_read_messages, though it never names the sibling 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?

Gives useful operational context — 'Without after_seq, only messages from now on' and 'With chat, other chats' messages are skipped and the answer may be empty' — which implies how to use it. But it never states when to prefer this over teams_read_messages or teams_list_chats, so the routing decision is left to inference.

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