List B2match notifications

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

Goes well beyond the annotations by disclosing that fetching resets B2match's unseen counter to 0 even though this client never sends ReadNotification, that the unread counter is unaffected, and that the full list requires a gated env flag. That is exactly the non-obvious side-effect information an agent needs before calling a nominally read-only tool.

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 tight sentences, front-loaded with the default behavior and followed by the side-effect and gating details in order of importance. No filler, though the phrasing is terse enough that a reader may need to re-read the env-var sentence.

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 return values, and it only characterizes them as counters versus a full list without describing notification fields or the shape of either mode. The side-effect disclosure is thorough, but the return-format gap leaves the definition minimally viable for a list tool.

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 after, event, first, and acknowledge_marks_seen are already documented in the schema (including acknowledge_marks_seen's env-var coupling). The description restates acknowledge_marks_seen's effect and adds that unseen resets, but adds nothing about after/first semantics, so the baseline of 3 is correct.

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 states the tool returns notification counters (unread/unseen) by default and can return a full list under a flag, which is a concrete resource and behavior. It does not name a sibling tool, but no sibling in the list is a close competitor (the rest are events, participants, meetings, conversations). The 'list' aspect is slightly underemphasized because the opening sentence leads with counters rather than the notification collection.

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 establishes clear context for the two modes: default behavior (counters) versus the full list, plus the explicit prerequisite B2MATCH_ALLOW_SIDE_EFFECT_READS=1 combined with acknowledge_marks_seen=true. It stops short of the 5-level bar because it names no when-not condition or alternative tools.

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