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

Annotations already declare the safe read-only/idempotent profile, so the bar is lower, and the description still adds real value: it discloses that secret material and destination paths are omitted, that membership is live rather than snapshotted, and that it requires the tickets:read scope. These are behaviors the annotations cannot express.

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 dense sentences, no filler, with the exclusions and scope semantics front-loaded before pagination mechanics. The phrasing 'Follow next_before_id while has_more' is terse to the point of slight ambiguity about which field the caller actually sends.

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 must describe returns, and it does so adequately by naming the returned metadata shape (no secrets/paths) and the pagination fields next_before_id and has_more. The unaddressed 'limit' parameter is the only material gap.

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?

With 0% schema description coverage the description must carry parameter meaning, and it does explain 'scope' semantics and the before_id/next_before_id cursor-plus-has_more loop. It says nothing about 'limit' (default 20, max 100), leaving one of three parameters undocumented in both schema and description.

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 a clear verb (list) and resource (owned notification rules/metadata) and immediately scopes what is excluded (destination paths, signing secrets). It implicitly separates this list tool from the sibling revision and delivery list tools, though it never names them explicitly.

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 explains when to pick each scope value ('active includes paused unarchived rules; archived/all also available'), which is genuine usage guidance. However, it gives no when-not guidance and does not route the agent to alternatives such as get_attention_notification_rule for a single rule or list_attention_notification_revisions for history.

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