← Fiction Editor

Tool Reference

117 MCP tools across 21 categories

Tools marked LLM require an LLM sampling call. Tools marked hybrid have a deterministic core with optional LLM analysis. All others run without LLM calls.

Project Setup 4

init_book Initialize a new greenfield fiction project. Creates meta.yaml and scaffolds the directory structure (chapters, manuscript, characters, settings, style/, acts, reviews, sessions, research, glossary) with placeholder files.
get_meta Return the book-level meta.yaml (title, genre, POV, tense, target, themes).
reload_index Rebuild the SQLite index from disk. Wipes every cached row and re-scans chapter outlines, scene files, and entities under the project root. Use when list_*/get_* results look inconsistent with the on-disk markdown (e.g. list_chapters reports chapters that get_chapter can't find, or act/pov metadata goes missing after an external edit).
check_metadata_drift Procedurally reconcile the SQLite index with on-disk files, then report scene summaries whose cached hash no longer matches the current body and classify each by how materially the body has diverged (trivial / minor / material / unknown). Use the material entries to drive follow-up summarize_scene calls; trivial entries are edits like punctuation fixes that don't warrant the token spend. Zero LLM cost — this is a mechanical hash + word-count check.

Characters 5

add_character Create a new character file. Slug auto-generated from name if not provided.
update_character Patch fields on an existing character. Only provided fields are changed.
get_character Return a single character's frontmatter + body.
list_characters List all characters with slug, name, role, and summary.
rename_character Rename a character file and sweep references across the entire project (all chapters, outlines, entity docs, glossary, reviews, frontmatter + body). If newName is provided, the display name is updated. If newNameVariants is provided, each variant (first name, last name, nickname) is also swept project-wide. Possessive forms like "Thomas's" are handled automatically.

Settings 5

add_setting Create a new setting (location, world, faction, culture).
update_setting Patch fields on an existing setting. Only provided fields are changed.
get_setting Return a single setting's frontmatter + body.
list_settings List all settings with slug, name, and sort.
rename_setting Rename a setting file and sweep references across the entire project (all chapters, outlines, entity docs, glossary, reviews, frontmatter + body). If newName is provided, the display name is updated. If newNameVariants is provided, each variant is also swept project-wide. Possessive forms are handled automatically.

Plot Devices 3

add_plot_device Add a recurring motif, object, mystery, macguffin, or symbol to the plot-devices list.
update_plot_device Patch fields on an existing plot device.
list_plot_devices List all plot devices with status and chapter setup/payoff.

Research & Glossary 6

add_research_note Add a research note with optional source/url/tags.
list_research_notes List research notes, optionally filtered by tag.
cite_research Record that a research note is referenced by a chapter.
add_glossary_term Add a glossary term (vocabulary, place, faction, concept) to the world.
update_glossary_term Patch fields on an existing glossary term. Only provided fields are changed.
list_glossary List glossary terms, optionally filtered by category.

Relationships 2

relationship_map Return the character relationship graph derived from each character's `relationships` frontmatter field. Edge targets may be other characters, settings (places, factions, cultures, organizations), or free-form external entities (corporations, governments, alliances). Each edge is labeled with the target's kind.
dedupe_entities Find likely duplicate characters/settings using Levenshtein similarity on name and slug. Returns candidate pairs above the given threshold (default 0.8).

Style Guide 2

update_style_guide Update the structured style guide (voice profile). Only provided fields are changed; arrays (favoredWords, bannedWords, etc.) replace the existing values when provided.
get_style_guide Return the current structured style guide (profile + prose notes).

Task Management 7

add_todo Add a todo to the editing backlog. IDs are human-readable: t-chN-MM, t-arc-MM, t-cont-MM (or t-{scope}-MM for custom scopes).
list_todos List todos, optionally filtered by tag, status (pending|active|done), or scope prefix.
complete_todo Mark a todo as done by ID.
link_todo_to_passage Attach a passage reference (e.g. manuscript/03-threshold.md:42) to a todo.
start_task Mark a todo as the active task. Only one task may be active at a time. Records a startedAt timestamp. The REPL prompt will show the active task.
complete_task Mark a task as done. Records completedAt timestamp and optional completion note. After completion, the agent should verify the work, trigger a scoped review of the edited content (chapter/act level based on the todo scope), and suggest the next task via next_suggested_task.
park_task Revert an active task back to pending. Clears startedAt. Use when switching to a different task or ending a session without completing.

Chapters & Scenes 13

add_chapter Create a new chapter outline at `chapters/NN-slug.md`.
list_chapters List all chapter outlines sorted by number.
get_chapter Fetch a chapter outline (by number or slug). Set includeProse=true to also return assembled prose.
set_chapter_status Update a chapter's workflow status (outlined|drafting|drafted|revised|final).
update_chapter_outline Patch chapter outline fields. Only provided fields are updated.
add_scene Create a new scene file under a chapter's manuscript directory.
update_scene Patch scene frontmatter and/or body. Only provided fields are updated.
scene_list List scenes in a chapter, sorted by order.
get_scene Fetch a scene's frontmatter plus either its full body (include=body, default) or its cached LLM summary (include=summary). Summary mode returns stale=true when no summary is cached yet.
assemble_chapter Read a chapter's full prose by concatenating its scene bodies.
read_chapter_chunk Stream a chapter's prose in scene-boundary chunks of approximately chunkSize words each (default 1500). Never splits mid-scene; a scene larger than chunkSize becomes its own chunk. Returns {chunkIndex, totalChunks, prose, sceneRange, chunkWords, totalWords, done}. Pass chunkIndex back incremented by 1 until done=true. Use this instead of assemble_chapter when a full chapter would blow past the context budget.
summarize_scenehybrid Return a 1-3 sentence summary of a scene. If a fresh summary is cached on the scene frontmatter (summaryCache + summaryCacheHash matching the current body hash) it is returned directly. Otherwise this tool returns a sampling request; after the host LLM replies, call set_scene_summary with {summary, bodyHash} to persist the result.
set_scene_summary Persist an LLM-generated scene summary to the scene's frontmatter. Requires the bodyHash returned by summarize_scene; refuses the write if the body has changed since the hash was computed (prevents stale summaries after concurrent edits).

Voice & Prose 11

voice_check Score a passage against the project style guide. Returns a 0.0-1.0 alignment score, bucket (aligned|minor-drift|notable-drift|voice-break), per-component sub-scores, and human-readable drift flags.
voice_diff Compare two passages (original vs proposed) for voice drift. Returns score deltas and flags that differ between the two.
scan_voice_drift Scan a chapter's scenes; flag scenes whose voice score falls below the given threshold (default = the 'minor-drift' cutoff from voice/thresholds).
lint_prose Deterministic prose lint (no sampling). Flags passive voice, repeated adjacent words, redundant acronyms, and indefinite-article errors. Use as a cheap pre-pass before critique_passage.
set_chapter_style_override Set per-chapter style profile overrides. Fields in the override take precedence over the narrator profile and global style guide when scoring voice drift for this chapter.
extract_character_voice Extract a StyleProfile from prose samples of a character (dialogue or POV narration). Stores the extracted profile on the character entity so it can be used by validate_character_voice and compare_narrator_voices.
validate_character_voice Score a chapter's prose against a character's stored voice profile. Also checks whether the character's verbalTics appear in the prose. The character must have a styleProfile (run extract_character_voice first).
compare_narrator_voices Compare voice profiles across narrators to ensure they sound distinct. Flags pairs whose cross-score is too high (voices too similar). Narrators must have stored voice profiles (via extract_character_voice).
analyze_voice_sample Extract a StyleProfile from a prose sample. Measures sentence + paragraph length, em-dash frequency, adverb tolerance, dialogue-tag habit. The extracted profile is self-consistent — scoring the sample against it returns ≈1.0.
calibrate_voice_thresholds Score every drafted scene against the current style profile and derive adaptive drift thresholds. Returns percentile cutoffs (P10/P25/P50) that suggest where to set the 'minor-drift' and 'notable-drift' thresholds for this manuscript. Also returns the distribution stats so the author can sanity-check before adopting.
check_pov_consistencyhybrid Scan a chapter for POV drift. Deterministic pass flags filter words (saw/heard/felt/realized/…) that dilute close-POV, and head-hop candidates (interiority attributed to a non-POV named character). Returns a sampling request for the host LLM to triage borderline findings.

Revision 4

diff_revision Produce a line-level unified diff between original and revised text. Returns added/removed counts and a diff listing.
backup_chapter Snapshot all scene files of a chapter to .fiction/backups/{timestamp}/. Run before applying revisions so the user can always roll back.
list_backups List prior chapter snapshots under .fiction/backups/.
apply_revision Apply a text replacement to a scene's body. `anchor` must be a unique substring in the existing body; it is replaced by `replacement`. By default, the chapter is backed up before the write.

Context & Consistency 5

gather_context Assemble lean per-chapter context for editing/critique: style guide, referenced character/setting summaries, prior-chapter beats (act-scoped by default), and continuity-tagged todos. Soft token budget ~2000.
check_tense_consistency Heuristic tense check: counts past-tense vs present-tense verb forms in the chapter's prose; flags if usage contradicts the chapter's declared `tense` or the project default.
character_arc_auditLLM Trace a character's appearances across chapters: list chapters where the character is declared (outline `characters[]`) or mentioned in prose, plus the character's declared arc string.
check_continuityhybrid Hybrid continuity check. Deterministic pass: name-variant detection (Levenshtein on capitalized tokens), entity-reference validation (declared characters/settings exist), timeline monotonicity. With includeLLM=true (default), also returns a sampling request for the host LLM to catch semantic continuity issues.
timeline Walk chapter (and optionally scene) outlines in narrative order and emit a chronological timeline keyed on inStoryDate. Flags narrative regressions (a later chapter dated before an earlier one) when dates are machine-parseable. Free-form dates are listed but not compared.

Critique & Review 9

critique_passageLLM Observe + suggest critique of a prose passage (NO rewriting). Returns a sampling request the host LLM must execute; response is a structured JSON with observations, suggestions, and flagged_spans. Focus areas: flow|tension|voice|dialogue|continuity|pov|tense|theme|show-dont-tell|cliche|prose-economy.
voice_preserving_revisionLLM Voice-firewalled revision. Default mode: coach-style suggestions, no prose. With allowProseGeneration=true, produces a single proposedText the caller must score via voice_check/voice_diff before applying. Returns a sampling request for the host LLM to execute.
theme_checkLLM Assess how well each project theme is embodied across a scope (chapter | act | all). Uses chapter outlines + declared themes only — never raw prose. Returns a sampling request for the host LLM.
review_chapterLLM Holistic multi-focus review of a single chapter. Assembles full prose + chapter outline metadata + prior-act beats, then returns a sampling request covering the requested focuses (defaults to structure, pacing, tension, voice, theme, pov). Observe + suggest only; no rewriting. `voiceStrictness` tunes how aggressively voice drift is flagged.
review_actLLM Act-level review using chapter digests (summary + beats + metadata). Pulls outline frontmatter first; when a chapter's outline is a stub, falls back to a rollup of scene frontmatter (summaryCache, beats, characters) so stub chapters aren't invisible to the reviewer. Returns a sampling request focused on act-scale shape: escalation, promises opened/paid, POV distribution, theme coverage.
review_arcLLM Story-arc review across all acts. Emits full per-chapter metadata (summary, beats, conflict, POV, emotion, characters, themes) grouped by act — outline frontmatter first, scene-frontmatter rollup when the outline is a stub. No raw prose. The reviewer is asked to name any chapter slugs that warrant deeper inspection via review_chapter, so the orchestrator can follow up with focused passes.
plan_novel_review Plan a coordinated novel review. Scans all chapters, computes the chunk plan (one chunk per chapter), and initializes a consistency ledger seeded with open promises. Use startChapter/endChapter to review a subset. Returns the plan + ledger for review_novel_chunk.
review_novel_chunkLLM Review a single chapter as part of a coordinated novel review. Pass the consistency ledger from plan_novel_review (or the previous chunk). If priorChunkResult is provided (the JSON string of the previous chunk's LLM response), its ledgerUpdates are merged into the ledger before building the request. Returns a sampling request.
synthesize_novel_reviewLLM Final synthesis pass for a coordinated novel review. Takes the completed consistency ledger and all per-chapter chunk results, compresses them into digests, and returns a sampling request for cross-novel analysis.

Reporting 6

stats Project-level statistics: wordcount by chapter, POV distribution, scene counts, todos grouped by tag. When includeProseCounts=false, skips reading scene bodies (faster; uses scene-frontmatter cache).
pacing_curve Markdown-table heatmap of per-chapter word counts against target words plus the chapter's declared emotionalTarget. Useful at a glance to spot overlong/underweight chapters and emotional flatness.
check_target_length Compare actual word counts to targets at chapter and project level. For chapters with prose, projects the final manuscript length assuming unwritten chapters hit their `targetWords` (falling back to per-project mean when absent).
tension_audit Per-chapter narrative of declared conflict + emotional target, flagging flat spots (runs of chapters with no internal/external conflict set) and emotional-target repetition (same target three chapters in a row).
next_suggested_taskLLM Recommend next actions based on backlog + chapter status + word-count deltas. Priorities (highest first): serious/continuity todos, drafting gaps (outlined chapters), voice/pacing todos, and unwritten chapters with target words.
session_notes Append a working note to `sessions/YYYY-MM-DD.md` (creating the file with a date header if absent). Date defaults to today (UTC).

Structure & Surgery 11

plan_chapterLLM Draft a chapter outline (beats + targetWords + conflicts + emotional target) from a premise + prior-act context. Returns a sampling request; the host LLM executes and you (or the user) decide whether to call add_chapter / update_chapter_outline with the result.
reorder_scenes Reorder scenes within a chapter by providing the new slug sequence. The provided list must contain every existing scene slug exactly once. Scene files and their `order` frontmatter are renumbered 0..N-1.
move_scene Move a scene from one chapter to another, inserting at `atOrder` (defaults to the end of the target chapter). Scenes on both sides are renumbered to keep orders contiguous; frontmatter `chapter` is updated to match the new chapter number.
split_chapter Split a chapter at a scene boundary. Scenes with order >= atScene are moved to a new chapter at `newNumber` (which must not collide with an existing chapter). The new chapter inherits act/pov/tense/themes from the original; body, beats, summary are left empty for the author to fill in. Scene orders in the new chapter are rebased to 0..N-1.
join_chapters Merge `from` chapter's scenes into `into` chapter, appending them in current order. Scene `order` is rebased into the target's sequence; scene `chapter` frontmatter is updated. The source outline and its (now-empty) manuscript directory are removed unless deleteFromOutline=false.
split_scene Split a scene at an anchor. The anchor must be a unique substring in the scene body; text before it stays in the original scene, text from the anchor onward becomes a new scene inserted immediately after. The new scene inherits pov/tense/characters/location from the original. Scenes later in the chapter shift up by one.
join_scenes Merge two adjacent scenes within a chapter. The first scene's body is extended with the separator and the second scene's body; the second scene's file is deleted and later scenes shift down by one. The merged scene keeps the first scene's slug, frontmatter, and title.
rename_scene Rename a scene's slug. Renames the scene file path (the slug is part of the path `manuscript/NN-chapterSlug/MM-sceneSlug.md`), updates the scene's frontmatter `slug` field, and refreshes the SQLite index. Scene slugs are chapter-scoped, so the rename fails only if the new slug already exists in the SAME chapter. Cross-references to the old slug (in reviews, the promise ledger, todos, chapter outlines, acts, research, glossary, timeline) are REPORTED but not auto-rewritten — scene slugs are not globally unique, so sweeping could touch unrelated scenes in other chapters. The caller decides which hits to fix.
generate_outline_draftLLM Draft a full-book chapter outline from a premise. Returns a sampling request; the response is an array of chapter summaries with act assignments, beats, and emotional targets. The author decides whether to feed the result into add_chapter calls.
critique_outlineLLM Structural critique of the current chapter outline. Flags pacing problems, unpaid promises, flat emotional arcs, act-boundary wobble, and theme gaps. Returns a sampling request; the response is JSON with observations, suggestions, and categorised concerns.
suggest_beatLLM Suggest additional beats for a chapter, fitting between or around existing beats. Returns a sampling request; the response lists positioned additions with rationale.

Promise Ledger 3

add_promise Register a new promise / Chekhov's gun to track. Returns the allocated promise id (p-NN). Status starts as open.
resolve_promise Mark a promise as paid (with paidChapter) or cut. Fails if the id is not registered. Idempotent: resolving an already-resolved promise overwrites its status.
promise_ledger List all tracked promises with status summary. If currentChapter is supplied, open promises whose expectedPayoff is at or before it are flagged 'overdue'. Set includeResolved=false to hide paid/cut entries.

Interview Wizards 2

interview_styleLLM Interview wizard to build/refine the author's style guide. Returns a sampling request that asks a batch of 4-7 questions. Round-trip: pass the author's answers back in priorAnswers for the next round.
interview_characterLLM Interview wizard to build/refine a character profile. Returns a sampling request asking 5-8 character-shaping questions. Round-trip answers via priorAnswers across multiple calls.

Import & Export 8

import_book Ingest an existing manuscript into the project. `path` may point to a single markdown/text file (split on ATX headings at `splitAt`, default level 1) or a directory of per-chapter files. Each chapter becomes a chapter outline plus a single scene (slug 'body'). Warns about preamble, missing headings, and renumbering conflicts.
extract_entitiesLLM Analyze manuscript prose and extract characters, settings, style observations, and plot devices. Returns a sampling request. Best used after import_book to seed the project with entities from an existing manuscript. Uses a representative sample capped at maxWords.
export_markdown_combined Combine all chapter prose into a single markdown manuscript file in the project's build/ directory. Scenes are joined by scene-break markers. If `renumber` is true (default), chapters are renumbered contiguously in the output regardless of any gaps in source numbering.
export_reader_preview Export a single chapter as a clean reader-facing markdown file (no frontmatter, scenes joined by scene breaks). Useful for sharing a chapter with beta readers.
export_typst Export the manuscript as a .typ (Typst) file via `pandoc -t typst`. If `compile` is true and the `typst` binary is present, also compile to manuscript.pdf. Requires `pandoc` on PATH.
export_epub_via_pandoc Export the manuscript as .epub via `pandoc -o manuscript.epub`. If `coverImage` is provided, passes it via --epub-cover-image. Requires `pandoc` on PATH.
build_character_bible Concatenate all character files into a single reference document. Emits a markdown file with one section per character (sorted by role then name) showing their voice profile, arc, goals, fears, and notes.
build_synopsisLLM Prepare a sampling request that drafts an agent-style synopsis of the book from its chapter outlines. Reveals the ending (synopses are for editors/agents, not readers). `length`: short (~250), standard (~750), or long (~1500) words.

Version Control 5

git_status Show working-tree status (staged, unstaged, untracked files).
git_add Stage files for the next commit.
git_commit Create a git commit with the given message.
git_diff_prose Show a word-level prose diff (--word-diff) for manuscript changes.
git_branch List branches, or create/switch to a branch by name.

Tool Discovery 2

list_tool_categories Discovery tool. **Call this whenever you need to modify project data** (scene frontmatter, chapter outlines, characters, settings, beats, metadata, todos, revisions, git) and don't see the specific tool you need in the current tool list. Only the 'reading' category is active by default; other categories must be enabled via enable_tool_category before their tools appear. Categories: reading (read-only orientation), drafting (create/edit scenes, chapters, characters, beats), revising (restructure, voice/POV, apply revisions), reviewing (critique, theme/arc audits), managing (todos, stats, style guide), setup (init, import, export, git). Never edit project markdown files directly — go through the fiction-editor tools.
enable_tool_category Activate a tool category so its tools appear in the next tools/list. Common cases: enable 'drafting' to edit scene metadata (update_scene), chapter outlines, characters, beats; enable 'revising' for structural surgery, voice/POV checks, apply_revision; enable 'reviewing' for critique and arc audits; enable 'managing' for todos and stats; enable 'setup' for import/export and git. Idempotent. Does not disable other active categories. Valid categories: reading, drafting, revising, reviewing, managing, setup.