novel_mutate
Make exact Novel Chapter structure, manuscript/private-note, metadata, checkpoint/restore or manual Writing Voice changes using native revision guards.
When to use
- Read current state with project_query(mode=novel), then submit the exact agreed action and native revisions in payload.
- Chapter structure uses base_outline_revision; split/merge/delete also require current manuscript revisions. Deleting prose, private notes or saved history requires confirm_prose_deletion=true; deletion archives the body and checkpoints. Deleted-Chapter recovery currently requires database tooling.
- Manuscript save uses chapter_card_id and payload.if_match_revision with a complete Novel Lexical body_json. Preserve existing private author-note blocks unless their editing or removal is requested.
- Omitted metadata fields and Chapter state remain unchanged. Changed manuscript saves automatically checkpoint the previous body.
- Voice save replaces the editable contract and proof_suite using expected_contract_revision and expected_proof_revision.
When not to use
- Generate or replan Chapters and write/revise prose with story_development_run; this tool saves exact supplied content.
- Read Novel state with project_query or resources. Foundation, Character and Thread card edits use story_mutate.
- Screenplay pages use screenplay_edit_* or screenplay_snapshot_apply; screenplay Voice uses screenplay_writing_voice.
Examples
- “Insert an empty Chapter at position 0 using chapter_insert and the observed outline revision.”
- “Save the author's Chapter prose and private notes with manuscript_save; use manuscript_checkpoint for a named milestone.”
- “Restore an observed checkpoint using manuscript_restore with revision_id and the current manuscript revision.”
Anti-examples
- Rewrite a Chapter from creative instructions; use story_development_run with manuscript_generation.
- Create or delete a Novel CHAPTER through generic story_mutate card operations.
Backend capabilities
novel.mutate
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
novel_mutate input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"project_id",
"operation",
"payload"
],
"properties": {
"project_id": {
"type": "integer",
"minimum": 1
},
"operation": {
"type": "string",
"enum": [
"chapter_insert",
"chapter_reorder",
"chapter_split",
"chapter_merge",
"chapter_delete",
"accept_length",
"manuscript_save",
"manuscript_metadata",
"manuscript_checkpoint",
"manuscript_restore",
"voice_save"
]
},
"chapter_card_id": {
"type": "integer",
"minimum": 1
},
"revision_id": {
"type": "integer",
"minimum": 1
},
"payload": {
"type": "object",
"description": "Exact native action body. Read current outline, manuscript or Voice revisions first. Manuscript bodies are complete Novel Lexical documents, including any private author-note blocks that must remain."
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"operation": {
"const": "chapter_insert"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_outline_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
},
"position": {
"minimum": 0,
"type": "integer"
},
"chapter": {
"additionalProperties": true,
"type": "object"
},
"chapter_updates": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"dependencies": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
}
},
"required": [
"base_outline_revision",
"position",
"chapter"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "chapter_reorder"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_outline_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
},
"chapter_ids": {
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"dependencies": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
}
},
"required": [
"base_outline_revision",
"chapter_ids"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "chapter_split"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_outline_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
},
"chapter_id": {
"minLength": 1,
"type": "string"
},
"if_match_manuscript_revision": {
"minimum": 0,
"type": "integer"
},
"first_chapter": {
"additionalProperties": true,
"type": "object"
},
"second_chapter": {
"additionalProperties": true,
"type": "object"
},
"chapter_updates": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"dependencies": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"first_body_json": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
},
"second_body_json": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"base_outline_revision",
"chapter_id",
"if_match_manuscript_revision",
"first_chapter",
"second_chapter"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "chapter_merge"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_outline_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
},
"first_chapter_id": {
"minLength": 1,
"type": "string"
},
"second_chapter_id": {
"minLength": 1,
"type": "string"
},
"first_manuscript_revision": {
"minimum": 0,
"type": "integer"
},
"second_manuscript_revision": {
"minimum": 0,
"type": "integer"
},
"merged_chapter": {
"additionalProperties": true,
"type": "object"
},
"chapter_updates": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"dependencies": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"merged_body_json": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"base_outline_revision",
"first_chapter_id",
"second_chapter_id",
"first_manuscript_revision",
"second_manuscript_revision",
"merged_chapter"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "chapter_delete"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_outline_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
},
"chapter_id": {
"minLength": 1,
"type": "string"
},
"if_match_manuscript_revision": {
"minimum": 0,
"type": "integer"
},
"confirm_prose_deletion": {
"type": "boolean"
},
"replacement_chapter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chapter_updates": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"dependencies": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
}
},
"required": [
"base_outline_revision",
"chapter_id",
"if_match_manuscript_revision"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "accept_length"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"base_length_revision": {
"pattern": "^[0-9a-f]{64}quot;,
"type": "string"
}
},
"required": [
"base_length_revision"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "manuscript_save"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"if_match_revision": {
"minimum": 0,
"type": "integer"
},
"body_json": {
"additionalProperties": true,
"type": "object"
},
"state": {
"anyOf": [
{
"pattern": "^(empty|draft|revised|approved)quot;,
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"if_match_revision",
"body_json"
],
"type": "object"
}
},
"required": [
"chapter_card_id"
],
"allOf": [
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "manuscript_metadata"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"if_match_revision": {
"minimum": 0,
"type": "integer"
},
"title": {
"anyOf": [
{
"maxLength": 240,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
]
},
"subtitle": {
"maxLength": 500,
"type": "string"
},
"byline": {
"maxLength": 240,
"type": "string"
},
"front_matter": {
"additionalProperties": true,
"type": "object"
},
"back_matter": {
"additionalProperties": true,
"type": "object"
}
},
"required": [
"if_match_revision"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "manuscript_checkpoint"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"if_match_revision": {
"minimum": 0,
"type": "integer"
},
"label": {
"anyOf": [
{
"maxLength": 120,
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"if_match_revision"
],
"type": "object"
}
},
"required": [
"chapter_card_id"
],
"allOf": [
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "manuscript_restore"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"if_match_revision": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"if_match_revision"
],
"type": "object"
}
},
"required": [
"chapter_card_id",
"revision_id"
]
}
},
{
"if": {
"properties": {
"operation": {
"const": "voice_save"
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"payload": {
"additionalProperties": false,
"properties": {
"contract": {
"additionalProperties": true,
"type": "object"
},
"proof_suite": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"maxItems": 64
},
"expected_contract_revision": {
"minimum": 0,
"type": "integer"
},
"expected_proof_revision": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"contract",
"proof_suite",
"expected_contract_revision",
"expected_proof_revision"
],
"type": "object"
}
},
"allOf": [
{
"not": {
"required": [
"chapter_card_id"
]
}
},
{
"not": {
"required": [
"revision_id"
]
}
}
]
}
}
]
}Output schema
novel_mutate output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"project_id",
"operation",
"result"
],
"properties": {
"project_id": {
"type": "integer"
},
"operation": {
"type": "string",
"enum": [
"chapter_insert",
"chapter_reorder",
"chapter_split",
"chapter_merge",
"chapter_delete",
"accept_length",
"manuscript_save",
"manuscript_metadata",
"manuscript_checkpoint",
"manuscript_restore",
"voice_save"
]
},
"result": {
"type": "object"
},
"credits_skipped_reason": {
"type": "string"
}
},
"additionalProperties": true
}← All toolsv1 · discriminated_mutate_tool