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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety baseline is covered; the description goes well beyond that by disclosing that the identifier is never reused, that restore returns the lesson with its links and versions intact, and that an elevated permission is required. These are exactly the consequence/permission details an agent needs before invoking a destructive call.

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?

Four short sentences, front-loaded with the action and its consequence, with no filler. The only friction is 'Say why before you do it', which implies a reason argument that does not exist in the schema and could briefly misdirect an agent.

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 single-parameter destructive tool with no output schema, the description supplies the destructive consequence, the reversibility path, and the permission requirement. Only the parameter's format and a clearer handling of the 'say why' expectation are missing.

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?

There is one parameter ('ref') at 0% schema description coverage, and the description only echoes it as 'by ref' without stating the identifier format, where to obtain it, or whether it accepts titles. It adds token value over the bare schema but does not 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 ('Delete a lesson by ref') and immediately names the sibling that undoes it (fenbs_restore_lesson), so it is distinguishable from the rest of the delete_* family at a glance.

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?

Names an explicit alternative (fenbs_restore_lesson) as the recovery path for this destructive action, and states a precondition ('Needs permission to change tasks') plus a required workflow step ('Say why before you do it'). It does not, however, contrast this with sibling deletes such as fenbs_delete_item, so routing among delete tools is left to inference.

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