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

Goes beyond the annotations by disclosing authority requirements (reviewer rights), the mitigating behavior that history is preserved, side effects on linked answers (fresh review requested), and replacement semantics (new immutable entry requiring separate promotion). It is consistent with destructiveHint=true and idempotentHint=true, though it omits failure/replay behavior that the schema-only idempotencyKey note implies.

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 short sentences front-load the core action, then prerequisites and consequences. Efficient with no redundancy, though the 'replacement needs its own promotion' clause blends two ideas that could be tighter.

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 destructive, idempotent mutation with no output schema, the description covers permissions, history preservation, downstream review, and the replacement path. It still leaves return/error behavior and three parameter meanings unaddressed, so it is solid but not complete.

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 coverage is only 40% (projectId and idempotencyKey are documented; entryId, revision, and reason are not). The description hints at revision via 'exact' but never explains entryId, the 64-hex revision format, or the reason field, so it fails to compensate for the coverage gap.

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 specific verb and resource ('retire the exact reusable answer') and implies revision-scoped targeting ('exact'), which separates it from siblings like reuse_library_entry and propose_library_entry. It does not name a sibling explicitly, so an agent must infer the distinction, keeping it below a 5.

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?

Provides a real prerequisite ('Requires reviewer rights') and hints at the after-state (replacement needs its own promotion), but never states when to retire versus alternatives such as retire_business_claim or simply superseding via propose_library_entry. Usage is implied rather than spelled out.

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