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

Annotations already declare destructiveHint and idempotentHint, so the description is not obligated to restate that — yet it adds real substance beyond them: the record is not physically removed (deletedAt is set), repeat calls yield ALREADY_DELETED, and notably the cleanup-cron clock is not refreshed. That last detail is non-obvious side-effect information an agent could not infer from any structured field.

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?

Two tight sentences with the core action front-loaded and the idempotency/cron nuance compactly parenthesized. No sentence is filler and nothing is buried.

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 mutation with no output schema, the description covers the semantics of the operation and the repeat-call outcome thoroughly. It leaves minor gaps: whether a deleted defect can be recovered (restore_defect) and what happens if the ID is unknown or already deleted beyond the ALREADY_DELETED code.

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 a single parameter at 100% schema description coverage, the schema already explains that defectId is the UUID of the defect. The description adds no additional meaning about the parameter (e.g. whether the UUID must reference a non-deleted defect), so the baseline of 3 applies.

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 precise verb and resource ('Soft-delete a defect') and immediately pins down what 'soft' means (sets deletedAt). This distinguishes it from a hard-delete sibling and from update_defect without needing to open the schema.

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 makes clear this is the reversible/soft removal path and that repeat invocation is safe, which is exactly the usage context an agent needs before deleting. It stops short of naming restore_defect as the undo path or stating prerequisites such as ownership/permission requirements.

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