lesson_restore

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

The description adds a meaningful behavioral detail beyond annotations: the tool explicitly refuses to overwrite an existing lesson with the same slug. This is useful safety context for an agent. Annotations are not contradicted, and while more side-effect detail could be added, the core guard is disclosed.

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 short sentences carry all essential information: the main action is front-loaded and the safety condition is stated separately. There is no redundant filler or repetition of schema details.

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 simple one-parameter tool with an output schema, the description covers the primary action and an important guard. However, it omits behavior when no trashed section exists, whether restoration can fail, and what happens in the overwrite-refusal case, leaving moderate ambiguity for the agent.

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 0%, so the description must compensate, but it only says 'for slug' without defining what the slug refers to, its format, or where to find it. The word 'slug' is repeated back without added semantic depth; a brief clarification of whether this is a lesson slug vs. section slug would help.

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 specifies the exact action ('Restore the latest trashed lesson section') and the target slug, making the tool's purpose immediately clear. It is distinct from sibling tools like lesson_remove, lesson_append, and curator_restore because it names the restoration of a trashed lesson section.

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?

There is no explicit guidance about when to choose this tool over alternatives such as lesson_append, lesson_patch, or curator_restore. The context is only implied by the word 'restore' and the refusal-to-overwrite guard, leaving the agent to infer usage scenarios.

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