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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and a closed world, so the safety profile is covered. The description adds real behavior beyond that: results are hard-scoped to the caller's inbox and never leak another user's rows, plus the default 50 / max 100 limit cap. It stops short of describing ordering or paging behavior.

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 sentences, zero filler, front-loaded with the resource and its key constraint before the filter list and the alternative routing. Each clause carries information an agent needs at call time.

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 return-shape burden, and it covers the important bits (what set is returned, the size cap). It would be marginally stronger if it stated the ordering of returned notifications or whether a cursor is returned at the 100 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 40%, but the description compensates by naming four of the five filters and their semantics: onlyUnread, type as a NotificationType value, since as an ISO date, and search matching title plus body. The 'search matches title + body' detail is genuinely additive over the bare schema. It does not enumerate valid NotificationType values, which is the one remaining gap.

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 and resource ('List the calling user's notifications') and immediately narrows scope to ctx.userId, explicitly denying cross-user access. It differentiates itself from near-name siblings by naming list_mentions and mark_notification_read as the tools for adjacent jobs.

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 routing rules: use list_mentions for @-mention drill-down and mark_notification_read to flip a single row read. That is genuine when-to-use-this-instead guidance. It does not address the other obvious alternatives in this cluster (dismiss_notification, dismiss_all_read_notifications, mark_all_notifications_read, list_notification_types), so it stops short of full coverage.

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