Restore a saved checkpoint to replace the active scene, invalidating topology refs. Verify state after restoration; if timeout occurs, reconcile before retrying.
Replace active scene with a verified checkpoint and invalidate all topology refs. May change scene or write files. Verify resulting state. A timed-out operation is UNKNOWN: reconcile_operation before any retry.
| Name | Required | Description | Default |
|---|---|---|---|
| checkpoint_id | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that this operation replaces the active scene, invalidates topology references, and may write files. It also warns that timeouts leave the state unknown and instructs reconciliation and verification, which are significant behavioral traits beyond the schema.
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?
All four sentences carry essential information: action, side effects, verification, and timeout handling. The most critical constraints are front-loaded before less urgent failure handling.
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?
The description covers purpose, side effects, post-verification, and timeout recovery, which is substantial for a single-parameter mutation without an output schema. It lacks an explicit statement of return value or prerequisites (e.g., the checkpoint must exist), but the instruction to verify resulting state compensates somewhat.
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?
The schema contains a single checkpoint_id string with no description (0% coverage). The description uses the phrase 'verified checkpoint' which implies the ID selects a previously created checkpoint, but it never explicitly maps checkpoint_id to a source or format, leaving the agent to infer parameter semantics from the name and tool context.
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 opens with a specific action: replace the active scene with a verified checkpoint, and it names a concrete side effect (invalidate all topology refs). This clearly differentiates it from sibling create_checkpoint and other scene tools without needing to open the schema.
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?
It provides a clear operational context (restore and then verify) and an explicit failure protocol: a timed-out operation is UNKNOWN, so reconcile_operation must be called before any retry. It does not list exclusions or compare directly with create_checkpoint, but the guidance is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.