scf_delete_comment

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

Annotations already mark destructiveHint=true, so the description is not expected to restate destructiveness. It adds value by disclosing the soft-delete nature (thread keeps place, body withdrawn) and the authorization requirement (author only). It does not mention reversibility, but this is a minor gap given the annotation already signals destruction.

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?

A single, front-loaded sentence that packs in the action, the permission model, and the structural consequence. Every word contributes information, with no fluff or repetition.

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?

For a one-parameter destructive action, the description covers what, who, and the behavioral effect. It does not describe the returned payload, but since no output schema exists and simple success/failure is expected, the essential context is adequate. Error cases (e.g., non-owned comment) are implied by the author-only constraint.

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 schema already provides a strong description for comment_id (format and provenance from scf_list_comments). The description adds the semantic constraint that the ID must reference a comment authored by the caller, which meaningfully narrows the valid value domain beyond what the schema describes.

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 verb 'retract' and the resource 'comment', and adds the constraint 'you authored' which immediately distinguishes it from scf_update_comment (which edits body text) and other scf_delete_* tools targeting different resources. The soft-delete clarification removes any ambiguity about the operation's effect.

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 provides clear context: the tool is only for comments the caller authored, and the soft-delete behavior implies when it is appropriate (retract a comment without removing the thread). It does not explicitly name alternatives or state 'use update_comment instead if you want to edit', but the verb and author-only constraint make the usage conditions sufficiently clear.

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