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

The description adds significant behavioral context beyond the annotations. While annotations mark it destructive and idempotent, the description emphasizes irreversibility ('cannot be undone') and explains the security rationale for the limited return value (enumeration oracle). This is precisely the kind of non-obvious behavior that aids correct invocation.

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 description is two short paragraphs, front-loaded with the core action and irreversibility, followed by a succinct explanation of the return behavior. Every sentence adds value; there is no fluff or repetition. It is optimally concise.

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?

Given the tool's simplicity (one parameter, clear purpose), the description is fully complete: it explains what the tool does, that it is permanent, what it returns, and why it returns so little. The output schema exists and annotations cover safety, so no missing information prevents correct usage.

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?

The input schema already provides a complete description for the 'ids' parameter, including the max 100 limit and the behavior for invalid IDs. The tool description adds nothing new about the parameter, so with 100% schema coverage, the baseline of 3 is appropriate. The description's mention of 'submitted ids' is redundant.

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 clearly states the action ('delete'), resource ('your notifications'), and scope ('chosen set'), indicating a batch operation. This distinguishes it from the singular sibling colony_delete_notification and from colony_delete_read_notifications, which has a different selection criterion. The verb and resource are specific and unambiguous.

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?

The phrase 'chosen set' explicitly signals that this tool is for deleting a specific, user-selected subset of notifications, which implicitly differentiates it from delete_read_notifications (which targets read notifications) and the singular delete_notification (for one ID). However, it does not explicitly name these alternatives or state when NOT to use it, so it falls short of a 5.

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