Research, planning, TTRPG & conlang

add_lexicon_words

Adds dictionary entries to a constructed language's lexicon. Each entry needs "word" and "gloss"; every other field of an entry -- part_of_speech, notes, ipa, semantic_field, inflection_class, etymology, opposite_gloss, components, senses -- may be sent in the SAME call, so a fully specified word takes one call, not two. Words already in the lexicon are skipped, never duplicated (use update_lexicon_word to change one).

Example call

{
  "name": "add_lexicon_words",
  "arguments": {
    "language": "<language>",
    "words": []
  }
}

add_source

Adds a bibliographic source to the research library: either one source from title/type/citation_key/fields (CSL variable names such as author, issued, container-title, publisher, page, URL), or many at once by passing "bibtex" text (Zotero/Mendeley exports).

Example call

{
  "name": "add_source",
  "arguments": {
    "bibtex": "<bibtex>",
    "citation_key": "<citation_key>"
  }
}

apply_beat_template

Chooses the story-structure template the project plots against -- three-act (three-act), the hero's journey (heros-journey), Save the Cat! (save-the-cat), or the Snowflake method (snowflake) -- by id or display name. Then map scenes to its beats with assign_beat. Scene assignments whose beat still exists are preserved.

Example call

{
  "name": "apply_beat_template",
  "arguments": {
    "template": "<template>"
  }
}

apply_content_pack

Overlays a content-pack folder onto the project: its categories and objects are added; anything already present (by id) is skipped, so re-applying a pack is idempotent. One undo step.

Example call

{
  "name": "apply_content_pack",
  "arguments": {
    "pack_dir": "<pack_dir>"
  }
}

assess_encounter

Rates a planned D&D 5e encounter for a party: the XP budgets, the count-adjusted encounter XP, the difficulty band, and a treasure guideline.

Example call

{
  "name": "assess_encounter",
  "arguments": {
    "party_size": 0,
    "party_level": 0,
    "foes": []
  }
}

assign_beat

Assigns a document (scene) to one beat of the applied structure template, or clears the beat with an empty "document".

Example call

{
  "name": "assign_beat",
  "arguments": {
    "beat": "<beat>"
  }
}

cite

Formats a citation for one source (addressed by title or citation key): the in-text form and the full bibliography entry, in APA, MLA, or Chicago.

Example call

{
  "name": "cite",
  "arguments": {
    "source": "<source>"
  }
}

create_language

Creates a constructed language (conlang). Only "name" is required; the sound system is seeded with sensible defaults so it can generate words and translate at once. Optional: consonants, vowels, patterns (C=consonant/V=vowel slots, e.g. "CV CVC V"), min_syllables, max_syllables, grammar_notes, and a "lexicon" of starter entries (which take the full entry shape, not just word+gloss).

Example call

{
  "name": "create_language",
  "arguments": {
    "name": "<name>"
  }
}

create_plot_thread

Creates a plot thread or character arc (unique name), with optional color ("#rrggbb"), description, and character (an entity name that makes the thread that character's arc).

Example call

{
  "name": "create_plot_thread",
  "arguments": {
    "name": "<name>"
  }
}

create_random_table

Creates a weighted random table (encounters, loot, rumours, ...). "entries" is an array of {text, weight} objects (or bare strings, weight 1); a higher weight is more likely. An outcome's text may nest: "[[2d6]]" (any dice expression) is replaced by a rolled total and "[[Other Table]]" rolls on that table, so tables chain into sub-tables. Roll on it with the roll tool.

Example call

{
  "name": "create_random_table",
  "arguments": {
    "title": "<title>"
  }
}

create_statblock

Creates a creature/NPC stat block. An optional template (dnd5e, pathfinder2e, custom) seeds that system's starter fields; provided stats/actions replace the starters, and system/notes are free text.

Example call

{
  "name": "create_statblock",
  "arguments": {
    "title": "<title>"
  }
}

create_task

Creates a task (unique title) with optional description, status (board column), board, priority (low|normal|high|urgent), due date (YYYY-MM-DD), and -- for a submission-tracker task -- submitted_to / submission_type / submitted_on / submission_notes.

Example call

{
  "name": "create_task",
  "arguments": {
    "title": "<title>"
  }
}

delete_plot_thread

Removes a plot thread (or character arc) from the project and untags every object that referenced it -- scenes, timeline events, and entities -- so nothing is left pointing at a deleted thread.

Example call

{
  "name": "delete_plot_thread",
  "arguments": {
    "thread": "<thread>"
  }
}

derive_daughter_language

Evolves a language's lexicon through an ordered list of sound-change rules into a new daughter language, added to the project. Each rule is written target -> replacement / environment (SCA2 style): "target" is the sound(s) that change, "replacement" what they become (empty deletes), and "environment" the context with _ for the target slot and # for a word boundary (e.g. V_V, _#). A subset of rules yields a dialect.

Example call

{
  "name": "derive_daughter_language",
  "arguments": {
    "language": "<language>",
    "daughter_name": "<daughter_name>",
    "rules": []
  }
}

export_codex

Compiles the codex world bible to output_path as md or html (chosen by "format" or the file extension). Optional audience. Entities marked "Exclude from AI" are omitted.

Example call

{
  "name": "export_codex",
  "arguments": {
    "output_path": "<output_path>"
  }
}

export_data

Exports a structured JSON slice of the project for migration, diff, or external tooling: "kind" is entities (fields, aliases, references resolved to names, lifespan), timeline (events with dates/participants/locations), sources, plot_threads, or continuity_rules. Names, not UUIDs, throughout; deterministic and diff-friendly. Returns the JSON directly, or writes it to "output_path" when given. "Exclude from AI" objects are omitted. Read-only.

Example call

{
  "name": "export_data",
  "arguments": {
    "kind": "<kind>"
  }
}

export_manuscript

Compiles and writes the manuscript to output_path (relative = inside the project folder) as md, html, docx, epub, or rtf (standard "Shunn" manuscript; give author/contact/pen_name). Optional audience and include_synopses. A legacy rich-text body is converted to Markdown on the way out, so the exported prose is clean in every format. Refused while any document -- or any object an embed pulls in -- is marked "Exclude from AI".

Example call

{
  "name": "export_manuscript",
  "arguments": {
    "format": "<format>",
    "output_path": "<output_path>"
  }
}

export_reference_grammar

Compiles the language into a shareable reference grammar as Markdown: sections for its sound inventory, phonotactics, orthography, grammar (typology, word order, paradigm tables, pronouns, numbers), and a sorted lexicon appendix.

Example call

{
  "name": "export_reference_grammar",
  "arguments": {
    "language": "<language>"
  }
}

export_screenplay

Exports one screenplay document to output_path as Fountain (default) or Final Draft (.fdx). The document's kind must be screenplay; its body is Fountain source.

Example call

{
  "name": "export_screenplay",
  "arguments": {
    "document": "<document>",
    "output_path": "<output_path>"
  }
}

export_script

Exports a language's script. "json" (the default) is the whole script INCLUDING the articulations that derived its glyphs, and re-imports exactly; "specimen" is every drawn glyph on one SVG sheet; "svg" is one glyph, named by "glyph".

Example call

{
  "name": "export_script",
  "arguments": {
    "language": "<language>"
  }
}

export_website

Builds the browsable static website (index with client-side search, chapter pages, and the world-bible codex pages) into output_dir. Optional audience and site_title. Refused while any document is marked "Exclude from AI"; excluded entities are omitted. Map pages need the desktop exporter and are not generated here.

Example call

{
  "name": "export_website",
  "arguments": {
    "output_dir": "<output_dir>"
  }
}

extract_document_text

Returns the plain text of a document file on disk — a PDF, a Word .docx, or a .txt/.md — so you can read a manuscript and build a project from it (create entities for its characters/places/items, add its timeline events, bring in its chapters) using the create_* tools. This does NOT run the app's automatic conversion; you are the intelligence. Reads document text only, never other files.

Example call

{
  "name": "extract_document_text",
  "arguments": {
    "path": "<path>"
  }
}

generate_vocabulary

Coins auto-glossed, semantic-field-tagged words for a set of meanings and appends the new ones to the language's lexicon (existing headwords are never duplicated). Give a "meanings" array, or use_swadesh=true to seed the ~100-word Swadesh core vocabulary. Deterministic per "seed".

Example call

{
  "name": "generate_vocabulary",
  "arguments": {
    "language": "<language>"
  }
}

generate_words

Coins candidate words from a language's phonology (structured phonotactics if set, else its consonant/vowel/pattern strings). Deterministic per "seed". The words are NOT added -- pass the ones you keep to add_lexicon_words.

Example call

{
  "name": "generate_words",
  "arguments": {
    "language": "<language>"
  }
}

get_analytics

Compiles the manuscript-health report as Markdown: word statistics, the dialogue/narration split, readability, point-of-view balance, a style-issue summary, and world-coverage counts (aggregates only -- no prose).

No parameters.

Example call

{
  "name": "get_analytics",
  "arguments": {}
}

get_beat_sheet

Shows the applied story-structure beat sheet: each beat, its target position in the story, and the scene assigned to it (or that it is still unfilled).

No parameters.

Example call

{
  "name": "get_beat_sheet",
  "arguments": {}
}

get_language

With no name, lists the project's constructed languages. With a name, shows the language's phonology, syllable bounds, lexicon size with sample entries, and grammar notes. Sample entries and long grammar notes are shortened unless "full" is true; ALWAYS pass full:true before rewriting the grammar notes or a lexicon entry, or the part you were not shown is lost when you write it back.

Example call

{
  "name": "get_language",
  "arguments": {
    "full": true,
    "name": "<name>"
  }
}

get_random_table

Reads a random table: its title, effective die size, and each weighted outcome with the die range that produces it.

Example call

{
  "name": "get_random_table",
  "arguments": {
    "table": "<table>"
  }
}

get_statblock

With no title, lists the creature/NPC stat blocks. With a title, shows the block's game system, statistics, actions, and notes.

Example call

{
  "name": "get_statblock",
  "arguments": {
    "title": "<title>"
  }
}

get_writing_system

Reads a language's constructed script: its kind, its three nested directions, how many glyphs are drawn of how many, its guides and variant markers, and a line per glyph. Pass "full": true for EVERY glyph -- the default shows a sample and says so, and rewriting the script from a partial reading replaces glyphs you never saw.

Example call

{
  "name": "get_writing_system",
  "arguments": {
    "language": "<language>"
  }
}

gloss_text

Produces a three-line interlinear (Leipzig) gloss of a passage written in the language: the source words, a morpheme gloss (inflected words show as root-FEATURE using the grammar's paradigms), and a free translation.

Example call

{
  "name": "gloss_text",
  "arguments": {
    "language": "<language>",
    "text": "<text>"
  }
}

import_file

Imports an external file or folder into the manuscript as one undo step: plain text / Markdown, an HTML file (.html/.htm, split into a document tree by headings), a PDF (.pdf, its extracted text), an Obsidian vault, a Notion export, yWriter (.yw6/.yw7), a Scrivener project, a Word document (.docx), a Manuskript project, or BibTeX (.bib, into the source library). "format" overrides auto-detection. "split" controls how a text/HTML/PDF file is broken into documents; "parent" nests the whole import under an existing document.

Example call

{
  "name": "import_file",
  "arguments": {
    "path": "<path>"
  }
}

list_plot_threads

Lists the plot threads and character arcs: colour, the character whose arc a thread is, how many scenes tag it, and its description.

No parameters.

Example call

{
  "name": "list_plot_threads",
  "arguments": {}
}

list_sources

Lists the project's bibliographic sources: title, kind, citation key, author, and date.

No parameters.

Example call

{
  "name": "list_sources",
  "arguments": {}
}

list_tasks

Lists tasks grouped by kanban board: done state, status column, priority, and due date. Optional board filter; pass include_done=false to hide completed tasks.

Example call

{
  "name": "list_tasks",
  "arguments": {
    "board": "<board>",
    "include_done": true
  }
}

remove_glyph

Removes one glyph from a language's script, leaving the rest alone.

Example call

{
  "name": "remove_glyph",
  "arguments": {
    "language": "<language>",
    "name": "<name>"
  }
}

remove_lexicon_word

Removes ONE dictionary entry from a constructed language, found by its headword. Every other entry is untouched -- unlike update_language, which replaces the whole lexicon.

Example call

{
  "name": "remove_lexicon_word",
  "arguments": {
    "language": "<language>",
    "word": "<word>"
  }
}

render_text

Sets a passage in a language's own script and returns it as SVG, honouring all three nested directions, ligatures, variant markers and connected-script joins. Any pen value you pass overrides the script's for this render only. Says how many glyphs are not drawn yet rather than silently returning a shorter passage.

Example call

{
  "name": "render_text",
  "arguments": {
    "language": "<language>",
    "text": "<text>"
  }
}

roll

Rolls dice ("3d6+2", "1d20", "4d6kh3") or on a named random table -- exactly one of dice/table. A table roll expands nested references in the outcome: "[[2d6]]" becomes a rolled total and "[[Other Table]]" rolls on that sub-table (recursively). Deterministic when a seed is given; the seed used is always reported so any roll can be replayed.

Example call

{
  "name": "roll",
  "arguments": {
    "dice": "<dice>",
    "seed": 0
  }
}

save_content_pack

Writes the chosen objects (addressed by title) plus every category they reference as a content-pack folder at output_dir, with an optional manifest (name/description/author/version). The project itself is not changed.

Example call

{
  "name": "save_content_pack",
  "arguments": {
    "objects": [],
    "output_dir": "<output_dir>"
  }
}

set_document_threads

Tags a scene (document) with the plot threads it advances, by thread name. The list REPLACES the scene's current threads; pass [] to clear them. Each name must be an existing thread (create_plot_thread first) so a scene never dangles a dead thread.

Example call

{
  "name": "set_document_threads",
  "arguments": {
    "document": "<document>",
    "threads": []
  }
}

set_entity_threads

Tags a codex entity with the plot threads it belongs to (a character's arc, a faction's storyline), by thread name. The list REPLACES the entity's current threads; pass [] to clear them. Each name must be an existing thread. Counts toward list_plot_threads.

Example call

{
  "name": "set_entity_threads",
  "arguments": {
    "entity": "<entity>",
    "threads": []
  }
}

set_event_threads

Tags a timeline event with the plot threads it belongs to, by thread name. The list REPLACES the event's current threads; pass [] to clear them. Each name must be an existing thread (create_plot_thread first). Counts toward list_plot_threads.

Example call

{
  "name": "set_event_threads",
  "arguments": {
    "event": "<event>",
    "threads": []
  }
}

set_grammar

Sets a language's structured grammar (replacing any existing). Anything you omit stays UNSET rather than taking a default, and an unset field is left out of the reference grammar instead of being asserted. Fields: "typology" (isolating/agglutinative/fusional/polysynthetic), "word_order" (SVO/SOV/VSO/VOS/OVS/OSV/free -- this is SENTENCE-level constituent order; for the order of roots INSIDE a word use position_classes), "adjective_position" (before/after), free "notes", "position_classes" ({position, role, fills, required}) giving the word's internal slot template, inflection "paradigms" ({name, applies_to, rules:[...]}), "pronouns" ({label, form, gloss}), and a "number_system" ({base, formation_note, digits:[{value, word}]}). A paradigm rule takes SIX fields: {feature, type, affix, root_word, position_class, uses_opposite_polarity}. type is none/prefix/suffix/circumfix/replacement/root; an unrecognised type is REJECTED, not coerced. Use type "root" with root_word + position_class + uses_opposite_polarity for a feature carried by a whole root in a slot -- e.g. a tense marked by which slot a root sits in and which pole it carries, which no affix type can express. gloss_text and spell_number then use all of it.

Example call

{
  "name": "set_grammar",
  "arguments": {
    "language": "<language>"
  }
}

set_orthography

Sets a language's spelling rules. Sparse -- it changes only the keys you pass, so setting one does not clear the others. "schemes" replaces the romanization schemes (each {name, mappings:[{phoneme, grapheme}]}); "default_scheme" names the preferred one; "polarity_marker" declares the mark that writes a word's OPPOSITE pole (e.g. an acute accent, so kor=knowledge and kor-with-acute=ignorance). Once declared, gloss_text and translate strip the mark before matching a headword and re-apply it when emitting an inverted sense, so marked forms read and write correctly.

Example call

{
  "name": "set_orthography",
  "arguments": {
    "language": "<language>"
  }
}

set_phonotactics

Sets a language's structured phonotactics (replacing any existing): named sound "categories" ({symbol, members}) that syllable "templates" ({shape, weight}) draw on, plus optional "rewrite_rules" ({match, replacement}), "forbidden_sequences", vowel "harmony_groups" (arrays of vowels), a "dropoff" (equiprobable/slow/medium/fast), and a "monosyllable_weight". generate_words then obeys them.

Example call

{
  "name": "set_phonotactics",
  "arguments": {
    "language": "<language>"
  }
}

set_script_metrics

Sets the drawing surface and the pen of a language's script, leaving its glyphs alone. "unit_kind" (phoneme/syllable/morpheme/word/free) decides what one glyph stands for; "directions" takes within_glyph, within_word and across_page SEPARATELY (ltr/rtl/ttb/btt), because a script can run its parts one way, stack its glyphs another and set its words a third; "anchored_ends" joins glyphs into a continuous line; "variant_triggers" maps a mark in the text to a named orientation.

Example call

{
  "name": "set_script_metrics",
  "arguments": {
    "language": "<language>"
  }
}

set_script_primitives

Sets the featural primitives a script assembles its glyphs from, and the composition rule that places them (replacing any existing). A script with nineteen primitives can imply well over a thousand symbols this way, all derivable, instead of a thousand hand-drawn outlines. Each primitive takes "strokes" (or an "svg_path") and "feature_tags"; each composition slot takes offset_x, offset_y, scale and fills.

Example call

{
  "name": "set_script_primitives",
  "arguments": {
    "language": "<language>"
  }
}

set_sound_changes

Sets a language's diachronic sound-change rulesets (replacing any existing). Each ruleset is {name, rules:[{target, replacement, environment}]} in SCA2 style; store them here, then evolve a daughter with derive_daughter_language.

Example call

{
  "name": "set_sound_changes",
  "arguments": {
    "language": "<language>",
    "rulesets": []
  }
}

set_writing_system

Sets a language's constructed script/conscript (replacing any existing). A script drawn symbol by symbol: "name", "direction" (ltr/rtl/ttb), "glyphs" ({name, grapheme, svg_path} -- svg_path is the outline in a 100x100 box), and "ligatures" ({sequence, glyph_name}). A FEATURAL script, whose symbols are assembled from a small set of parts (the Hangul model): give "primitives" ({id, name, grapheme, feature_tags, svg_path}) and a "composition" ({slots:[{offset_x, offset_y, scale, fills}], joined}) instead, and the inventory is generated rather than hand-drawn -- a few dozen primitives can imply thousands of symbols. A glyph or ligature then names "primitive_ids" in slot order. "directions" ({within_glyph, within_word, across_page}) sets the three nested directions separately, for a script whose parts, glyphs and words do not all run the same way. "no_descenders" records that every glyph sits above the writing line. A glyph's "variants" ([{name, transform}]) give its alternate orientations without drawing a second symbol. transform is mirror-y (flip across a HORIZONTAL axis -- top and bottom swap and the parts KEEP their left-to-right order, so the flipped form still reads forwards), mirror-x (flip across a vertical axis -- the order reverses), rotate180, rotate90 or rotate270. An unknown transform is rejected.

Example call

{
  "name": "set_writing_system",
  "arguments": {
    "language": "<language>"
  }
}

spell_number

Spells an integer in the language's number system (its base and numeral words), composing multi-digit numbers from the place words.

Example call

{
  "name": "spell_number",
  "arguments": {
    "language": "<language>",
    "value": 0
  }
}

translate

Translates text word-by-word through a constructed language's lexicon. direction: to_conlang (default) or from_conlang. Words missing from the lexicon pass through verbatim and are reported so they can be coined.

Example call

{
  "name": "translate",
  "arguments": {
    "language": "<language>",
    "text": "<text>"
  }
}

update_language

Edits a language's name, sound system, syllable bounds, or grammar notes. Only the fields given change; new_name renames it. An explicit "lexicon" REPLACES the whole dictionary -- use add_lexicon_words to append without disturbing existing words.

Example call

{
  "name": "update_language",
  "arguments": {
    "language": "<language>"
  }
}

update_lexicon_word

Edits ONE dictionary entry in place, found by its headword. Only the fields you send are changed; everything else on the entry is left alone. Use this to correct a gloss -- add_lexicon_words skips a word that already exists, and update_language REPLACES the whole lexicon, so correcting one entry through it destroys every entry you did not resend.

Example call

{
  "name": "update_lexicon_word",
  "arguments": {
    "language": "<language>",
    "word": "<word>"
  }
}

update_plot_thread

Updates one plot thread (addressed by name). Sparse: new_name, color ("#rrggbb", "" = default), description, character (an entity name to bind the thread as that character's arc, "" to clear).

Example call

{
  "name": "update_plot_thread",
  "arguments": {
    "thread": "<thread>"
  }
}

update_random_table

Sparse update of a random table: "new_title" renames it; "entries" replaces the whole weighted-outcome list. One undo step.

Example call

{
  "name": "update_random_table",
  "arguments": {
    "table": "<table>"
  }
}

update_source

Updates one source (addressed by citation key or title). Sparse: new_title, type, citation_key replace their values; "fields" merges the provided CSL keys (an empty value removes that key).

Example call

{
  "name": "update_source",
  "arguments": {
    "source": "<source>"
  }
}

update_statblock

Edits an existing stat block. Only the fields given change; new_title renames it. A supplied "stats" or "actions" array REPLACES that whole list (omit it to leave the list untouched); system and notes are free text.

Example call

{
  "name": "update_statblock",
  "arguments": {
    "title": "<title>"
  }
}

update_task

Updates one task (addressed by title). Sparse: only the provided keys change -- new_title, description, status (board column), board ("" = the default board), done, priority (low|normal|high|urgent), due (YYYY-MM-DD, "" clears). For a submission-tracker task the submission-pipeline fields submitted_to / submission_type / submitted_on / submission_notes are set here too (the response-due date IS "due" and the pipeline stage IS "status").

Example call

{
  "name": "update_task",
  "arguments": {
    "task": "<task>"
  }
}

upsert_glyph

Creates or edits ONE glyph in place, without rewriting the script. Sparse: a key you omit is left alone, so correcting a unit cannot erase a drawing. "strokes" is the drawn form ([{points:[{x,y,pressure,corner}], closed, smoothing, pen_scale}], coordinates 0..1 in the glyph box); "primitive_ids" composes it from featural parts instead; "variants" names alternate orientations.

Example call

{
  "name": "upsert_glyph",
  "arguments": {
    "language": "<language>",
    "name": "<name>"
  }
}