holonovel

Novel Archive Management

manage_archive

Destructive

Export, import, archive, unarchive, clone, branch, and manage checkpoints for novel state, with dry-run, merge, replace, and strict import modes plus undoable restores.

Instructions

Manage Novel archival and checkpoint surfaces. Export writes a file; import writes Novel state and mode selects dry-run (validate only), merge (keep existing entries), or replace (discard current Novel state), while strict aborts on unresolved references. archive is reversible with unarchive; checkpoint_restore replaces the live Novel with the stored checkpoint and is itself undoable; checkpoint subscriptions persist. Use when: exporting or importing a Novel, archiving/unarchiving, cloning/branching, or managing checkpoints. Do NOT use when: creating, resuming, renaming, or ending a Novel — use manage_novel. Revert the most recent mutation with manage_history (action: undo); checkpoint_list is read-only.

Input Schema

Name	Required	Description
`data`	No	Exported Novel JSON (import).
`mode`	No	dry-run, merge, or replace (import).
`slug`	No	Novel slug (resume/switch/archive/unarchive/info).
`label`	No	Checkpoint label (checkpoint_set/list/restore/remove).
`scope`	No	Export scope (export).
`action`	Yes	export, import, archive, unarchive, clone, branch, checkpoint_set, checkpoint_list, checkpoint_restore, checkpoint_remove.
`format`	No	Output format (export).
`strict`	No	Fail on any cross-reference mismatch (import).
`new_name`	No	Name for the copy or branch (clone/branch).
`from_event`	No	Event-log ordinal to branch from (branch; default latest).
`source_slug`	No	Novel to copy or branch from (clone/branch).
`include_checkpoints`	No	Include checkpoints in export (default false; export).
`trim_audit_sessions`	No	Keep only the most recent N sessions' audit entries in the clone (clone; default full copy).

Output Schema

Name	Required	Description	Default
`text`	No	Human-readable text envelope mirroring the structured result (REQ-001, REQ-548a).
`status`	Yes	Machine-readable result status: OK, NEED_INPUT, WARNING, PARTIAL, or an error category (REQ-002, REQ-548c).

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv2026.10.13Oct 25, 2026

removedInput schema / properties / codex_adventure

Removed value: -{
-  "description": "Codex adventure to seed from (create).",
-  "type": "string"
-}

removedInput schema / properties / current_scene

Removed value: -{
-  "description": "Current-scene summary (save_context).",
-  "type": "string"
-}

removedInput schema / properties / description

Removed value: -{
-  "description": "Description (create/description).",
-  "type": "string"
-}

removedInput schema / properties / detail

Removed value: -{
-  "description": "Return full metadata (list).",
-  "type": "boolean"
-}

removedInput schema / properties / filter

Removed value: -{
-  "description": "active, archived, or all (list).",
-  "enum": [
-    "active",
-    "archived",
-    "all"
-  ],
-  "type": "string"
-}

removedInput schema / properties / genre

Removed value: -{
-  "description": "Genre tag (create/genre).",
-  "type": "string"
-}

removedInput schema / properties / immediate_situation

Removed value: -{
-  "description": "Immediate situation (save_context).",
-  "type": "string"
-}

removedInput schema / properties / long_term_plans

Removed value: -{
-  "description": "Long-term plans (save_context).",
-  "type": "string"
-}

removedInput schema / properties / name

Removed value: -{
-  "description": "Novel name (create).",
-  "type": "string"
-}

removedInput schema / properties / new_slug

Removed value: -{
-  "description": "New slug (rename).",
-  "type": "string"
-}

removedInput schema / properties / pending_player_action

Removed value: -{
-  "description": "Pending player action (save_context).",
-  "type": "string"
-}

removedInput schema / properties / player_goals

Removed value: -{
-  "description": "Player goals (save_context).",
-  "type": "string"
-}

removedInput schema / properties / ruleset

Removed value: -{
-  "description": "Ruleset slug (create).",
-  "type": "string"
-}

removedInput schema / properties / short_term_plans

Removed value: -{
-  "description": "Short-term plans (save_context).",
-  "type": "string"
-}

AddedOct 22, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real substance: export writes a file, import writes Novel state, 'replace' discards current Novel state, strict aborts on unresolved references, archive is reversible via unarchive, and checkpoint_restore is undoable. It stops short of stating permission/auth requirements or what validate-only dry-run returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is front-loaded with operation semantics first, then the Use/Do-NOT-Use routing, and every clause carries new information. The middle sentence is long and packs four mode behaviors plus strict into one run-on, which costs some scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-action, 13-parameter tool with an output schema and safety annotations, the description covers the risky paths (import modes, replace, checkpoint_restore) and the sibling routing well. Gaps are minor: clone/branch semantics (what actually gets copied, how trim_audit_sessions interacts with a full copy) and export scope/format options live only in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantics of 'mode' beyond the enum labels (dry-run = validate only, merge = keep existing entries, replace = discard current state) and by clarifying what 'strict' aborts on. Clone/branch parameters such as trim_audit_sessions and from_event are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates the concrete operations (export, import, archive/unarchive, clone/branch, checkpoint_*) it covers on Novel state, and explicitly separates itself from manage_novel. The opening verb 'Manage ... surfaces' is an umbrella phrase, but the following clauses supply the specific verbs the name alone would obscure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit 'Use when' list (export/import, archive/unarchive, cloning/branching, checkpoints) and a 'Do NOT use when' clause routing Novel CRUD to manage_novel. It also names two further alternatives with their roles: manage_history (action: undo) for reverting mutations and checkpoint_list as the read-only counterpart.

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