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

Goes well beyond the annotations: it discloses that the tool reads Spaces' own event stream rather than the platform, making repeated calls safe, describes the long-poll timing (returns immediately if events exist, otherwise waits up to wait_seconds, default 30, cap 50), and states the 14-day event retention. Cursor continuation semantics — next_cursor as after, resumption from the key's last position, 24-hour default backlog, after: now to skip — are behavior an agent could not infer from readOnlyHint alone.

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?

Dense but front-loaded: the core behavior comes first, then the loop guidance, then cursor handling, then per-event-type handling. Long, yet nearly every clause supplies decision-relevant information (timing, retention, which field to skip, which tool to call next).

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?

No output schema exists, so the description must cover returns, and it does — event categories, message.received payload fields (text up to 1,000 chars, text_truncated, sender, chat_id, is_sender), and next_cursor for continuation. The main gaps are the unexplained limit parameter and the absence of the overall response envelope shape.

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 0% schema coverage the description carries the full burden and largely does: it explains after (cursor continuation and defaults), wait_seconds (default 30, max 50), types (a list used as a filter), and account_id. The limit parameter (1–200) is never mentioned, leaving one of five parameters undocumented.

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?

States a specific verb (waits for / checks) and resource (new messages and events on connected accounts), then enumerates the event categories returned. It explicitly distinguishes itself from list_messaging_chats and list_messaging_messages, so an agent can select it without opening another schema.

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 explicit when-to-use ('call it in a loop instead of calling list_messaging_chats or list_messaging_messages'), when-not (repeated platform checks look like a bot and can get an account restricted), and downstream routing for specific event types (reply_in_chat for message.received, submit_review after consent for review.invite, add_card_url for billing). The condition for falling back to list_messaging_messages is also stated.

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