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

Goes beyond annotations (readOnlyHint=false, destructiveHint=true) by clarifying the non-destructive nature: 'the current live state is first saved as a new restore version' and 'a restore can itself be undone by restoring that backup.' Also explains backup_version_id null behavior and that the restored state is recorded as a history entry. This is rich, context-adding transparency.

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?

The description is dense but every sentence earns its place. It opens with the core action, moves to target selection, then safety/undo behavior, then the backup edge case, then guidance to consult history, and closes with return shape and auth. No repetition or 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 mutating tool with nested parameters, no output schema, and several edge cases, the description covers all necessary context: how to choose the target, what the backup/undo behavior is, the return fields, and the access/retention requirements. An agent has everything needed to call it correctly.

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 description coverage is 100%, so parameters are already well-documented. The description adds value by explaining the preferred choice among the three version identifiers (revision_id preferred, stable across renames) and by elaborating the backup semantics and return object, which enriches parameter understanding beyond the schema.

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 states a specific verb and resource: 'Restore the model to a previous version' and details the effect ('replacing the current items, schema, and inputs with that snapshot'). It clearly distinguishes from sibling tools by focusing on restoring a version rather than listing (layerz_history), diffing (layerz_diff), or other operations.

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 explicit guidance on target selection ('exactly one of revision_id, version_number, or id'), names the preferred option, and instructs to 'Pick the target by reading layerz_history / layerz_diff first.' It also states prerequisites: write access, retention window, and read-only key restrictions.

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