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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description consistently reinforces those while adding real substance: the body is retained server-side for audit but blanked on read, the row remains as a tombstone, and repeat deletion is a no-op. It also documents the `serialization_retry` error and the instruction to retry verbatim, which is valuable operational context. The 3 reflects strong alignment plus added detail rather than contradiction.

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?

Front-loads the action, then layers permissions, retention semantics, idempotency, and error handling in a logical order with no filler sentences. It is dense and parenthetical-heavy, which slightly raises reading cost, but every sentence contributes information an agent needs.

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?

With no output schema, the description compensates by explaining what the caller observes after deletion (blanked body, tombstone in thread) and which error signals a safe retry. For a two-parameter, annotated mutation tool this covers nearly everything an agent needs, shorting only on whether the call returns anything meaningful.

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 both `commentId` and `reason` are already documented, including that `reason` is recorded on the comment.deleted event. The description restates the `reason` behavior and adds nothing about `commentId` beyond the schema, so this is a baseline case where the schema carries the load.

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?

Opens with a specific verb+resource pairing ('Soft-delete a comment'), and 'soft' immediately separates it from a hard removal or an edit. It does not name a sibling such as skein_comment_update to contrast against, so differentiation is inferred rather than stated.

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 authorization conditions: the author may always delete their own comment, otherwise the caller must be an owner/admin of the project, and a plain non-author member receives `forbidden`. That is a clear usage boundary, though no alternative tool is named for the case where the caller wants to edit rather than remove a comment.

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