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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. Above that baseline the description adds real value: revisions are immutable, the payload exposes sensitive 'private destination URLs', it requires notifications:manage, and it explicitly returns no signing secrets. Ordering and cursor-following behavior are also disclosed.

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 what the tool returns, followed by pagination mechanics and the permission/no-secret constraints. No filler or repetition of the schema.

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, but the description notes the ordering (newest first) and the pagination fields (next_before_revision, has_more), plus access requirements and sensitive content. That is sufficient for an agent to page through results correctly; only the exact return shape is left implicit.

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 0%, so the description carries the burden, and it only partially compensates. It explains the pagination cursor (before_revision -> 'next_before_revision while has_more') but says nothing about the required rule_id or the limit/default of 20. It adds cursor semantics beyond the bare schema but leaves two parameters unclarified.

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: reading immutable notification configuration revisions, with the distinguishing detail 'newest revision first' and mention of contents (private destination URLs, frozen selection). An agent can distinguish this from list_attention_notification_rules because the subject is revisions of a rule, not rules themselves. It stops short of explicitly naming the sibling alternatives, so 5 is not warranted.

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 operational usage ('Follow next_before_revision while has_more') and a permission prerequisite ('Requires notifications:manage'), but no guidance on when to choose this over list_attention_notification_rules, get_attention_notification_rule, or the delivery/receipt listing tools. Usage is implied by the resource rather than contrasted with alternatives.

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