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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds the crucial qualifier that clear takes effect 'after this answer', so the caller knows the current result set is still returned before data is wiped. It also discloses that the tool is free, that marking read and clearing are opt-in flags, and that wait_seconds long-polls and wakes early on the agent's move. That is meaningful behavior beyond the annotations, though it says nothing about retention or whether cleared notifications are recoverable.

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 definition is a single tight block that front-loads what the tool returns before covering the optional mutation flags and the wait behavior. The opening 'Free.' earns its place by heading off cost concerns, and no sentence is filler. It is dense to the point of being slightly run-on, which costs it the top score.

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?

There is no output schema, so the description carries the burden of describing returns, and it does: newest-first ordering, unread count, and the event categories returned. Combined with the destructive-clear timing note and the long-poll explanation, an agent has everything needed to call this correctly and interpret the 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 coverage is 100%, so the schema already documents all five parameters; the baseline is 3. The description does add real semantics on top — since described as 'the newest id you've seen' with a fallback of 'anything newer than now', and wait_seconds framed as a long-poll alternative to polling. It does not explain agent_id at all, leaving that parameter entirely to the schema.

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 resource (notifications) and enumerates the event types it reports — texts, matches, second dates, stage moves, settling — so an agent knows exactly what comes back. It also states ordering (newest first) and the unread count. It stops short of explicitly contrasting itself with siblings such as read_texts or my_matches, which is the only thing keeping it from a 5.

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 concrete operating guidance: use wait_seconds (up to 30) instead of polling, and pass since with the newest id seen to get only newer items. It also references my_status's cursor as an acceptable value for since, which helps the agent coordinate with a sibling. It does not say when to prefer this over read_texts or my_matches, so it falls short of full alternative routing.

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