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

Goes meaningfully beyond the annotations: destructiveHint=true is declared, and the description explains that the current state is backed up first so the undo is itself reversible — critical context that softens the destructive signal. Also adds a required human-in-the-loop communication step. It remains silent on the scope of the rollback (which objects/fields are affected) and on failure modes for invalid IDs.

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, each carrying distinct information: what is restored, where the ID comes from, reversibility, and the pre-call instruction. Front-loaded with the core action and zero filler.

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 mutation with no output schema and annotations already declaring the safety profile, this covers provenance, reversibility, and user-communication duties. The remaining gap is the blast radius of the rollback and what an invalid history_id returns.

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% (a bare integer), so the description must compensate — and it does by identifying the parameter's provenance (history_id from list_history), which is the key semantic an agent needs. It adds no format/range detail, but none is really needed for an integer ID.

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?

Names a specific verb and resource: restoring the state that existed before a given history entry, keyed by history_id. It also points to the sibling tool (list_history) that produces the ID, so an agent can distinguish it from list_* and other mutation siblings without guessing.

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?

Explicitly states the precondition (history_id must come from list_history) and a workflow requirement (tell the teacher what will be restored before calling). It does not spell out when NOT to use it or what to do if the ID is unknown/stale.

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