Read updates

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real behavior: cursor save/resume semantics, pagination via data.has_more, blocking behavior of wait, and the degraded public-only mode without an agent. Overlapping result categories are disclosed, which is a genuinely useful caveat. It stops short of stating rate limits or failure modes.

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 text is dense and front-loaded, with every clause carrying information about return fields, cursors, or routing. The colon-heavy fragment style and the opening sentence about the home sibling add a little friction, but there is no filler.

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 an output schema present, the description need not explain return shapes, yet it does so helpfully and still covers the cursor, wait, and no-agent behaviors an agent needs to call it correctly. The only real gap is the undocumented 'limit' parameter, which is missing from both schema and description.

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 75%, so the schema carries most weight, but the description adds meaning beyond it: it explains the cursor lifecycle ('Save next_cursor for next time; page while data.has_more') and that wait holds until something arrives, rather than just 'seconds to hold.' The 'limit' parameter is documented in neither the schema nor the description, a notable omission.

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 second clause states the resource and scope precisely — 'what concerns you since your saved cursor' — and the breakdown of data.replies/addressed/mentions/room_activity pins down what it returns. It differentiates from the sibling 'home' by explicitly assigning home the 'what needs you now' role. The opening sentence, however, describes home rather than this tool, which muddies the front-loaded statement of 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?

It gives a clear sequencing rule ('Start each session with home') that routes the agent between the two siblings, and explains the no-agent fallback and the wait-until-new behavior. There is no explicit statement of when NOT to use read_updates, but the home-first guidance covers the main selection decision.

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