Skip to main content

Chat Tools

Chat tools are callable functions the Chat assistant can use inside Lis Novel chats.

They are available only in Chat (not in prompt templates or editor automation), and they can both read and write data.

Scope, safety, and behavior​

  • Scope: tools run against the active novel.
  • Lore scope: lore tools include the active novel and (when present) its series-scoped lore/fields.
  • No web access: tools only read/write local Lis Novel data.
  • Hidden lore: lore entries with aiVisibility = hidden are excluded unless explicitly allowed by attached lore context.
  • AI-hidden sections: scene manuscript/content exposed to tools omits section blocks marked hideFromAi=true.
  • Soft-deleted content: tools operate on active records (deleted scenes/chapters/acts/notes are excluded).
  • Confirmation: destructive actions require confirm: true (or throw a confirmation-required error).

Global limits​

  • Lore/note/scene search tools: default limit = 20, max 50.
  • Scene excerpt tools: default excerptSize = 160, max 400.
  • get_scenes: max 200 scene ids.
  • get_novel_outline_snapshot: max 500 scoped scenes.
  • analyze_scene_summary_alignment: max 200 analyzed scenes.
  • create_scene_beats: 1..50 beats per call.
  • list_lore_fields: default limit = 200, max 500.

Lore tools​

search_lore_entries​

Search by name, aliases, tags, or description.

  • Inputs: query (required), includeAliases (default true), includeTags (default true), limit.
  • Returns: { matches: LoreEntrySummary[] } with name, type, aiVisibility, customDetails, xml.

list_lore_entries​

List lore entries (optionally by type).

  • Inputs: type?, limit (default/max 50).
  • Returns: { matches } with id, type, aliases, tags, description.
  • Note: does not return name.

get_lore_entry​

Fetch one lore entry.

  • Inputs: id (required), includeCustomDetails (default true).
  • Returns: { loreEntry } or { loreEntry: null }.

list_lore_fields​

List custom detail fields.

  • Inputs: limit (default 200, max 500), collects? (entry type filter).
  • Returns: { fields }.

get_lore_field​

Fetch one lore field.

  • Inputs: id (required).
  • Returns: { field } or { field: null }.

create_lore_entry​

Create a lore entry.

  • Inputs: name?, type? (default other), description?, aliases?, tags?, aiVisibility?, scope? (novel|series), details?.
  • aiVisibility values: visible | always | manual | hidden.
  • Returns: { loreEntry }.
  • Note: Chat lore tools use description as the lore body text field. Lore notes stay available in the Lore UI but are not exposed to Chat tools.

update_lore_entry​

Update lore entry core fields, arrays, and details.

  • Inputs: id (required), plus any of: patch, aliases, tags, details, customDetails, confirm?.
  • patch.aiVisibility values: visible | always | manual | hidden.
  • Returns: { loreEntry }.
  • Note: use patch.description for lore body text updates; Chat tools do not read or write Lore Entry notes.
  • Confirmation rule: required for destructive changes (type change or detail clears).

delete_lore_entry​

Delete a lore entry.

  • Inputs: id (required), confirm.
  • Returns: { deleted: { id, name, type } }.

create_lore_field​

Create a custom detail field.

  • Inputs: name, type (text|line|dropdown|lore_reference), collects?, aiContext?, showInList?, scope?, options?.
  • Returns: { field }.
  • Note: options are only valid for dropdown fields.

update_lore_field​

Update a custom detail field.

  • Inputs: id, patch, confirm?.
  • Returns: { field }.
  • Confirmation rule: required when changing field type.

delete_lore_field​

Delete a custom detail field.

  • Inputs: id, confirm.
  • Returns: { deleted: { id, name, type } }.

create_lore_field_option​

Create a dropdown option.

  • Inputs: loreFieldId, label?, color?.
  • Returns: { option }.

update_lore_field_option​

Update a dropdown option.

  • Inputs: id, patch (label?, color?, position?).
  • Returns: { option }.

delete_lore_field_option​

Delete a dropdown option.

  • Inputs: id, confirm.
  • Returns: { deleted: { id, label } }.

reorder_lore_field_options​

Reorder dropdown options for a field.

  • Inputs: loreFieldId, optionIds (ordered list).
  • Returns: model reorder result.

set_lore_entry_details​

Set/clear detail values for one entry.

  • Inputs: entryId, details (required), clear?, confirm?.
  • Returns: { loreEntry }.
  • Confirmation rule: required when clearing details.

batch_update_lore_entries​

Run multiple lore-entry updates in one call.

  • Inputs: updates (required), confirm?.
  • Returns: { results } (per-entry updated or error).
  • Note: batch lore text updates use patch.description; Chat tools do not expose Lore Entry notes.
  • Confirmation rule: required when batch includes destructive changes.

Note tools​

search_notes​

List active notes; optionally compute match scope against a query.

  • Inputs: query? (default empty), scope (title|content|both, default both), limit.
  • Returns: { matches } with id, name, matchScope (title|content|both|none).
  • Note: when query is empty, notes are still listed with matchScope = none.

get_notes​

Fetch notes by id with content rendered to Markdown.

  • Inputs: ids (required, 1..50).
  • Returns: { notes } in requested id order (missing ids are omitted).

create_note​

Create a note.

  • Inputs: name?, content? (TipTap JSON), contentText?, favourite?.
  • Returns: { note }.

update_note​

Update a note.

  • Inputs: id (required) and at least one of name, content, contentText, favourite.
  • Returns: { note }.

delete_notes​

Delete one or many notes.

  • Inputs: id?, ids?, confirm.
  • Returns: { deleted }.
  • Rules: requires at least one id and confirm: true.

Scene search tools​

search_scenes_by_phrase​

Search manuscripts and/or summaries with excerpts.

  • Inputs: query (required), scope (manuscript|summary|both), limit, excerptSize.
  • Returns: { matches } with scene/act/chapter metadata plus excerpt.
  • Manuscript scope uses AI-visible prose only (Scene Beats and sections with hideFromAi=true are omitted).

search_scenes_by_label​

Find scenes by label id or label name.

  • Inputs: labelId?, labelName?, limit (one of labelId/labelName required).
  • Returns: { matches }.
  • Note: labelName matching is case-sensitive.

search_scenes_by_pov​

Find scenes by POV character and optional POV type.

  • Inputs: characterId (required), povType?, limit.
  • Returns: { matches }.

search_structure_by_phrase​

Search structure text and optionally group results.

  • Inputs: query (required), level (scene|chapter|act, default scene), limit, excerptSize.
  • Returns: { matches } (flat scene matches or grouped chapter/act matches).
  • Scene prose search text uses AI-visible prose only (sections with hideFromAi=true are omitted).

Structure tools​

get_story_structure​

Get active novel structure.

  • Inputs: none.
  • Returns: { novelId, structureMode, acts }.
  • Scene content in returned structure is sanitized for AI visibility (section blocks with hideFromAi=true are removed).

get_scenes​

Fetch scene metadata + plain-text manuscript.

  • Inputs: ids (required, 1..200).
  • Returns: { scenes }.
  • manuscript contains AI-visible prose only (Scene Beats and sections with hideFromAi=true are omitted).

get_novel_outline_snapshot​

Get structure + word-count snapshot.

  • Inputs: actIds?, chapterIds?, sceneIds?, includeSummaries?, includeManuscriptPreview?, previewChars?, maxScenes?.
  • Returns: { novel, scope, scenes } with aggregate counts/stats.

analyze_scene_summary_alignment​

Analyze summary/prose alignment.

  • Inputs: actIds?, chapterIds?, sceneIds?, maxScenes?, keywordLimit?, previewChars?.
  • Returns: { novel, scope, totals, scenes } with alignment scores, signals, and recommendations.

create_act​

Create an act.

  • Inputs: title?, numerate?.
  • Returns: { act }.
  • Mode rule: only in acts_chapters_scenes.

update_act​

Update an act.

  • Inputs: id, title?, numerate?.
  • Returns: { act }.
  • Mode rule: only in acts_chapters_scenes.

delete_act​

Delete an act.

  • Inputs: id, confirm.
  • Returns: { act }.
  • Mode rule: only in acts_chapters_scenes.

reorder_acts​

Reorder acts.

  • Inputs: actOrder (must include all active act ids exactly once).
  • Returns: { success: true }.
  • Mode rule: only in acts_chapters_scenes.

create_chapter​

Create a chapter.

  • Inputs: actId?, title?, numerate?.
  • Returns: { chapter }.
  • Mode rule: unavailable in scenes_only.

update_chapter​

Update/move chapter.

  • Inputs: id, actId?, title?, numerate?.
  • Returns: { chapter }.
  • Mode rule: unavailable in scenes_only.

delete_chapter​

Delete a chapter.

  • Inputs: id, confirm.
  • Returns: { chapter }.

move_chapter​

Move chapter to another act/position.

  • Inputs: chapterId, toActId, toIndex?.
  • Returns: { success: true }.
  • Mode rule: only in acts_chapters_scenes.

reorder_chapters​

Reorder chapters in an act.

  • Inputs: actId, chapterOrder (full ordered set).
  • Returns: { success: true }.

create_scene​

Create a scene.

  • Inputs: chapterId?, subtitle?, summary?, includeInContext?, pov?, contentJson?, contentText?.
  • Returns: { scene }.
  • Note: if chapterId is omitted, the tool uses/creates default act/chapter.
  • Note: returned scene.content is sanitized for AI visibility (sections with hideFromAi=true are removed).

create_scene_beats​

Insert beat blocks into a scene manuscript.

  • Inputs: sceneId?, beats (required, 1..50), insert? (append|prepend, default append), clearExistingBeats?.
  • Returns: { sceneId, beatsCreated, beatIds, resolvedSceneId, insert, clearExistingBeats }.
  • Note: if sceneId is omitted, the most recently created active scene is used.

update_scene​

Update scene metadata/manuscript.

  • Inputs: id (required) + at least one update field (subtitle, summary, includeInContext, pov, contentJson, contentText).
  • Returns: { scene }.
  • Note: returned scene.content is sanitized for AI visibility (sections with hideFromAi=true are removed).

delete_scene​

Delete a scene.

  • Inputs: id, confirm.
  • Returns: { scene }.
  • Note: returned scene.content is sanitized for AI visibility (sections with hideFromAi=true are removed).

move_scene​

Move a scene to another chapter/position.

  • Inputs: sceneId, toChapterId, toIndex?.
  • Returns: { success: true }.

reorder_scenes​

Reorder scenes in a chapter.

  • Inputs: chapterId, sceneOrder (full ordered set).
  • Returns: { success: true }.

apply_outline_blueprint​

Apply generated outline data to the novel.

  • Inputs: mode? (append|replace_existing), structureMode?, acts?, chapters?, scenes?, confirm?.
  • Returns: { applied, mode, counts }.
  • Rules: at least one of acts|chapters|scenes is required.
  • Confirmation rules:
    • mode = replace_existing requires confirm: true.
    • changing structureMode requires confirm: true.

split_scenes_into_chapters​

Create chapter buckets and move existing scenes.

  • Inputs: actId?, chapters (required), removeEmptyChapters?, confirm?.
  • Returns: { success: true, createdChapterIds }.
  • Rules:
    • unavailable in scenes_only.
    • each sceneId can appear only once in the request.
    • removeEmptyChapters: true requires confirm: true.

Practical usage patterns​

  • Character lookup: search_lore_entries -> get_lore_entry.
  • Notes retrieval: search_notes -> get_notes.
  • Scene audit: get_novel_outline_snapshot -> analyze_scene_summary_alignment.
  • Structure edits: create_scene / create_scene_beats / update_scene, then reorder or move tools.
  • Bulk lore updates: batch_update_lore_entries for multi-entry cleanup.