Skip to main content

Chat Tools

Chat tools are data lookups the Chat assistant can call to retrieve story information (lore, scenes, labels). They are only available in Chat, not in standard prompt templates or editor automation.

Use them in your Chat prompts to instruct the assistant when to look things up. The assistant decides which tool to call based on your instructions.

What these tools can access​

  • Scope: The active novel and its series lore (if the novel belongs to a series).
  • No external data: Tools do not browse the web.
  • Visibility: Lore entries with aiVisibility: hidden are excluded. Other visibility modes can be returned.
  • Search limits: Most tools default to 20 matches, max 50. Excerpts default to 160 chars, max 400.

Quick usage patterns​

  • Find a lore entry by name, then pull details: search_lore_entries → get_lore_entry.
  • Find where a phrase appears: search_scenes_by_phrase or search_structure_by_phrase.
  • Find scenes by tag or POV: search_scenes_by_label or search_scenes_by_pov.

Tool reference​

list_lore_entries​

Lists lore entries, optionally filtered by type.

Inputs

  • type (string, optional): lore entry type filter.
  • limit (number, default 50, max 50): number of entries to return.

Returns

  • matches: array of objects with id, type, aliases, tags, description.

Notes

  • Does not return the entry name. Use get_lore_entry for names and full details.

search_lore_entries​

Search lore by name, aliases, tags, description, or notes.

Inputs

  • query (string, required): search phrase.
  • includeAliases (boolean, default true): include alias matches.
  • includeTags (boolean, default true): include tag matches.
  • limit (number, default 20, max 50).

Returns

  • matches: array of objects with id, name, type, aliases, tags, aiVisibility, description, notes, customDetails, xml.

get_lore_entry​

Fetch a single lore entry by id.

Inputs

  • id (string, required): lore entry id.
  • includeCustomDetails (boolean, default true): include custom field values.

Returns

  • loreEntry: object with id, name, type, aliases, tags, aiVisibility, description, notes, customDetails, xml, or null if not found.

search_scenes_by_phrase​

Search scene manuscripts and/or summaries for a phrase and return excerpts.

Inputs

  • query (string, required).
  • scope (string, default both): manuscript, summary, or both.
  • limit (number, default 20, max 50).
  • excerptSize (number, default 160, min 20, max 400).

Returns

  • matches: array of objects with scope, sceneId, sceneTitle, actId, actTitle, actNumber, chapterId, chapterTitle, chapterNumber, sceneNumber, matchIndex, excerpt.

Notes

  • Search is case-insensitive.
  • Manuscript search excludes beat blocks.

search_scenes_by_label​

Find scenes tagged with a label.

Inputs

  • labelId (string, optional): label id to match.
  • labelName (string, optional): label name to match (case sensitive).
  • limit (number, default 20, max 50).

Returns

  • matches: array of objects with sceneId, sceneTitle, actId, actTitle, actNumber, chapterId, chapterTitle, chapterNumber, sceneNumber, labels.

Notes

  • Either labelId or labelName is required.

search_scenes_by_pov​

Find scenes by POV character (and optional POV type).

Inputs

  • characterId (string, required): lore entry id of the POV character.
  • povType (string, optional): POV type filter.
  • limit (number, default 20, max 50).

Returns

  • matches: array of objects with sceneId, sceneTitle, actId, actTitle, actNumber, chapterId, chapterTitle, chapterNumber, sceneNumber, povType.

search_structure_by_phrase​

Search story structure for a phrase and optionally group matches by chapter or act.

Inputs

  • query (string, required).
  • level (string, default scene): scene, chapter, or act.
  • limit (number, default 20, max 50).
  • excerptSize (number, default 160, min 20, max 400).

Returns

  • If level: "scene": matches is an array like search_scenes_by_phrase.
  • If level: "chapter" or "act": matches is an array of groups with actId, actTitle, actNumber, optional chapter fields, plus a matches array of scene excerpts.

search_notes​

Search notes by title and/or content. Returns metadata only (no note content).

Inputs

  • query (string, required): search phrase.
  • scope (string, default both): title, content, or both.
  • limit (number, default 20, max 50).

Returns

  • matches: array of objects with id, name, matchScope (title, content, or both).

Notes

  • Search is case-insensitive.
  • Note content is not included; use get_notes to fetch full content.

get_notes​

Retrieve notes by id with full content as Markdown.

Inputs

  • ids (array of strings, required): list of note ids to retrieve (1..50).

Returns

  • notes: array of note objects, ordered to match the requested ids.
    • Each note includes standard note fields and content rendered as Markdown.

Notes

  • Notes not found are omitted from the response.

create_note​

Create a note in the current novel. Supports plain text or TipTap JSON content.

Inputs

  • name (string, optional): note title. Whitespace-only titles are saved as null.
  • content (object, optional): TipTap JSON content.
  • contentText (string, optional): plain text to be converted into TipTap JSON.
  • favourite (boolean, optional): favorite flag.

Returns

  • note: the created note record.

Notes

  • If both content and contentText are provided, content wins.
  • If no content is provided, an empty note body is created.

update_note​

Update a note in the current novel. Supports plain text or TipTap JSON content.

Inputs

  • id (string, required): note id to update.
  • name (string, optional): note title. Whitespace-only titles are saved as null.
  • content (object, optional): TipTap JSON content.
  • contentText (string, optional): plain text to be converted into TipTap JSON.
  • favourite (boolean, optional): favorite flag.

Returns

  • note: the updated note record.

Notes

  • At least one field to update is required.
  • If both content and contentText are provided, content wins.

update_lore_field_option​

Update a dropdown option for a lore custom detail field.

Inputs

  • id (string, required): lore field option id.
  • patch (object, required):
    • label (string, optional): option label.
    • color (string or null, optional): option color. Allowed values: purple, orange, blue, green, gray, red, yellow, pink, brown, black. Use null to clear the color.
    • position (number, optional): option sort position.

Returns

  • option: the updated option record.

Example Chat instructions​

Example 1: Find a character, then pull details

When I ask about a character, use search_lore_entries to find candidates by name.
If there is a clear match, call get_lore_entry and summarize the character in 3 sentences.

Example 2: Locate a phrase in summaries

If I mention a recurring motif, search scene summaries with search_scenes_by_phrase
(scope = "summary") and list the scene titles that mention it.

Example 3: Filter by label

When I ask for flashbacks, use search_scenes_by_label with labelName = "Flashback".
Return the scene titles in story order.

Example 4: POV audit

If I ask for POV coverage, first search_lore_entries for the character by name,
then use search_scenes_by_pov with the characterId to list every scene.