Embers: Tabletop RPG Toolkit
Server Details
Characters, campaigns, adventures & worlds for D&D 5e/5.5e, Pathfinder, Savage Worlds, Fate, & more.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- OAuth
- Works in Glama
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 168 tools
Tools are domain-prefixed (imagine_, play_, vault_) and most descriptions explicitly disambiguate near-neighbors, but with 168 tools there are many genuinely confusable clusters: play_list_my_characters vs play_list_campaign_characters vs vault_search_characters vs vault_search_monsters, play_list_pages vs play_list_user_pages vs imagine_list_world_pages vs imagine_search_world_pages, and play_delete_character vs vault_delete_character (detach vs destroy). The ten imagine_generate_*_name tools and the many list_*_campaigns variants also invite misselection under time pressure.
The overwhelming majority follow domain_verb_noun snake_case (vault_update_character, play_add_campaign_rule, imagine_create_world_page), which is highly predictable across a 168-tool surface. Minor deviations exist: unprefixed outliers (whoami, list_rulesets, create_submission, upload_submission_screenshot), verb_in_noun (imagine_replace_in_adventure_page), and verb_noun_verb (play_check_recap_exists).
168 tools is far past any reasonable ceiling for a single MCP server, well into the extreme-mismatch band. Even acknowledging that the server bundles four or five distinct products (vault, play, imagine, submissions, social), the effective choice set per task is enormous and the surface should be split into separate servers or drastically trimmed.
Lifecycle coverage is near-exhaustive: full CRUD for adventures, worlds, pages, campaigns, sessions, characters, items, rules, and spells, plus legacy/edge flows like conversion, linked sheets, companions, PBEM inbox, party order, level-up, and character building. Cross-domain integration (worlds↔campaigns, adventures↔sessions, vault↔play) is explicitly wired in both directions, leaving few dead ends.
Available Tools
168 toolscreate_submissionReport a bug or request a featureAInspect
File a bug report or a feature request with Embers on the calling user's behalf. Pass type (bug or request), a short title, and a description. Optional attachments are ids from upload_submission_screenshot. Returns the created submission; the user can track it with list_my_submissions and get_submission.
Inputs: type (required), title (required), description (required), attachments. Returns: object
get_submissionRead one of my submissionsARead-onlyIdempotentInspect
Read one of the calling user's submissions: the original report, its screenshots, the current status, and the activity feed (replies both ways and status changes). Pass submissionId from list_my_submissions. Another user's submission is forbidden.
Inputs: submissionId (required). Returns: object
imagine_add_character_to_worldAdd a Character to a WorldAIdempotentInspect
Add a vault Character (any type, monsters included) to a World. A Character can be in at most 10 Worlds at once (400 for one more). While the Character's owner can view the World, the Character is offered what the World adds as house rules, is not offered the stock content the World hides (unless another of its Worlds keeps it), gets the World's extra skills of its ruleset as skill rows it does not already have, written now, and is offered the World's extra damage types of its ruleset. The caller must be able to edit the Character and view the World (403 otherwise). Adding a Character already in the World changes nothing. Returns { characterId, worlds: [{ _id, name, link }], updatedAt, addedSkills }: every World the Character is now in, in the order it joined them, the Character's new updatedAt (adopt it for a following vault_update_character; null when the Character was already in the World and nothing changed), and the skill rows the add stored on it.
Inputs: id (required), characterId (required). Returns: object
imagine_add_world_damage_typeAdd an extra damage type to a WorldAInspect
Add an extra damage type to a World for one ruleset. A Character of that ruleset in the World is offered it, beside the ruleset's own damage types, in its sheet's editors: an action's damage line and a Monster's immunities, resistances, and vulnerabilities. Adding it writes to no Character. Returns 201 { houseDamageType: { _id, ruleset, name } }; 409 when the name is already a damage type of the ruleset or of the World in that ruleset (names match ignoring case); 400 for a name that is not one damage type's or a ruleset that takes none. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.
Inputs: id (required), name (required), ruleset. Returns: object
imagine_add_world_house_ruleAdd a rule, spell, or item to a World's house rulesAIdempotentInspect
Add a vault rule, spell, or item to a World's house rules. Every Character in the World whose ruleset matches the record's is offered it (in vault's pickers, character creation, and level-up), and the World's linked campaigns get it as a house rule too. Adding a stock record the World hides makes it a house rule instead. Adding a record the World already has changes nothing. Caller must be able to edit the World (its owner, a contributor, or an admin with Admin Mode on).
Inputs: id (required), entityId (required), entityType (required). Returns: object
imagine_add_world_skillAdd an extra skill to a WorldAInspect
Add an extra skill to a World for one ruleset. A Character of that ruleset gets it as a skill row with this ability and description and no proficiency when it joins the World, is built with the World chosen, or levels up while in the World; adding the skill writes to no Character now. Returns 201 { houseSkill: { _id, ruleset, name, attribute, description } }; 409 when the World already has a skill of that name in the ruleset. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.
Inputs: id (required), name (required), ruleset, attribute, +1 more. Returns: object
imagine_create_adventureCreate an adventureAInspect
Create a new adventure owned by the calling user. Required: name and ruleset (imagine has no app-wide ruleset default for adventures). Other fields pass through to imagine.
Inputs: name (required), ruleset (required), link, image, +16 more. Returns: object
imagine_create_adventure_pageCreate an adventure pageAInspect
Create a new page inside an adventure. Required: adventureId, name. Use this for scene descriptions, encounter rooms, NPC profiles, plot beats. Valid documentType values: generic, act, scene, location, character, handout, lore, appendix, map. Items and rules are NOT page types; author them in vault and reference them, not as adventure pages. Set the tags array so the page is filterable in adventure-page listings; the page's documentType is also auto-added to the searchable keyword set.
Inputs: name (required), adventureId (required), map, goal, +20 more. Returns: object
imagine_create_worldCreate an imagine worldAInspect
Create a new world owned by the calling user. Required: name. Other fields (summary, description, link) pass through to imagine, which validates and assigns defaults where appropriate. Worlds do not carry a ruleset of their own; ruleset lives on the adventure(s) under the world instead.
Inputs: name (required), link, menu, image, +11 more. Returns: object
imagine_create_world_pageCreate a world pageAInspect
Create a new page inside a world. Required: worldId, name. Use this for NPCs, locations, organizations, events. Valid documentType values: generic, character, location, organization, event, lore, religion, cosmology. Items and rules are NOT page types; author them in vault and reference them, not as world pages. Set the tags array so the page is filterable via imagine_list_world_pages_by_tags; the page's documentType is also auto-added to the searchable keyword set. Pass visibility: 'gm' for a GM-only page (seen only by the world's owner, its contributors, and an admin with Admin Mode on; 404 and absent from lists for everyone else) or visibility: 'masked' for a page that participates in lists and backlinks under maskName ('Redacted' when unset) with its real name, link, and content hidden until revealed.
Inputs: name (required), worldId (required), link, tags, +24 more. Returns: object
imagine_delete_adventureDelete an adventureADestructiveIdempotentInspect
Soft-delete an adventure by id. The adventure is moved to the user's deleted-adventures list and can be restored from the imagine UI. Pages inside are tombstoned with it. Caller must be the adventure's owner or an admin with Admin Mode on; contributors get 404. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
imagine_delete_adventure_pageDelete an adventure pageADestructiveIdempotentInspect
Permanently delete an adventure page by id. Imagine does not soft-delete pages, so this is unrecoverable. Caller must own or have edit access on the page. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
imagine_delete_worldDelete an imagine worldADestructiveIdempotentInspect
Soft-delete a world by id. The world is moved to the user's deleted-worlds list and can be restored from the imagine UI. Pages and adventures inside are tombstoned with it. Caller must be the world's owner or an admin with Admin Mode on; contributors get 404. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
imagine_delete_world_pageDelete a world pageADestructiveIdempotentInspect
Soft-delete a world page by id. The page is moved to the world's trash, keeps its link and aliases reserved, and can be restored from the imagine UI for 45 days before it is purged permanently. Caller must own or have edit access on the page. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
imagine_generate_braxylian_nameGenerate Braxylian namesARead-onlyInspect
Generate hard-edged names from the Braxyl, the plains culture of the world Veylantia — guttural men, flowing women. kind chooses person or place; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_draconic_nameGenerate draconic namesARead-onlyInspect
Generate dragon names using the harsh phonetics of the Draconic tongue. Returns an array of names.
Inputs: count, length, includeEpithet. Returns: object
imagine_generate_gallance_nameGenerate Gallance namesARead-onlyInspect
Generate melodious, French-flavored noble names from the Gallance culture of the world Veylantia. kind chooses person, place, or house; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_lorean_nameGenerate Lorean namesBRead-onlyInspect
Generate plain, weathered names from the Lorean Freeholds, the refugee holdfasts of the world Korinth. kind chooses person or place; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_npcGenerate an NPCARead-onlyInspect
Generate a random NPC with personality, occupation, and (optionally) a secret. Returns an NPC object.
Inputs: includeSecret. Returns: object
imagine_generate_pelegorian_nameGenerate Pelegorian namesARead-onlyInspect
Generate soft, melodic, Mediterranean-flavored names from Pelegor, the seafaring city-states of the world Veylantia. kind chooses person or place; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_shoren_nameGenerate Shoren namesBRead-onlyInspect
Generate clipped, consonant-struck names from Shoren, a country of the world Veylantia. kind chooses person / place / house; for people, gender is mixed / male / female. Returns an array of names.
Inputs: kind, count, gender. Returns: object
imagine_generate_strykaran_nameGenerate Strykaran namesARead-onlyInspect
Generate names from the Strykaran people of the world Veylantia — soft and Slavic-flavored. kind chooses person or place; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_tarithan_nameGenerate Tarithan namesARead-onlyInspect
Generate hard, lyrical names from Tarithan, the mountain realm of the world Veylantia. kind chooses person or place; for people, gender (mixed/male/female) and surname apply. Returns an array of names.
Inputs: kind, count, gender, surname. Returns: object
imagine_generate_thalassan_nameGenerate Thalassan namesARead-onlyInspect
Generate vowel-flooded, sibilant names from Thalassa, the sea culture of the world Veylantia. kind chooses person / place / house; for people, gender is mixed / male / female. Returns an array of names.
Inputs: kind, count, gender. Returns: object
imagine_get_adventureGet an adventureARead-onlyIdempotentInspect
Fetch one adventure by id with its settings, ruleset, recommended level, and any user-linked play campaigns. The campaign link is informational only and is set by the user; imagine and play do not auto-sync state between them. If the adventure is one part of a series, parent is populated as { _id, name, link, active } — use imagine_list_adventure_parts on the parent id to see the sibling parts. Caller must have at least 'view' access, with one exception: on a PRIVATE adventure with linked play campaigns, a caller who is a member (the owner or any accepted seat, watchers included) of one of those campaigns gets a minimal recaps-only shape instead of a 403 — { _id, name, link, image, recapsOnly: true, hasLinkedCampaigns: true }, enough to call imagine_get_adventure_recaps, none of the adventure content. Non-owner viewers of public adventures get a hasLinkedCampaigns boolean in place of the stripped playCampaignIds.
Inputs: id (required). Returns: object
imagine_get_adventure_pageGet an adventure pageARead-onlyIdempotentInspect
Fetch one adventure page by id with its full markdown body, tags, and parent reference. By default the gateway dereferences bracketed tag-* and child-* shortcodes and inlines a compact <expansion> block right after each literal. (rule-* shortcodes are NOT expanded on adventure pages because adventures do not carry a curated rule / spell / item association list; they remain as literals.) Pass raw: true to skip expansion when round-tripping the body back through imagine_update_adventure_page. Cross-references in the response: parent (resolve via imagine_get_adventure_page), worldPageRefs (array of world-page ids, resolve via imagine_get_world_page), and vaultRefs (array of {vaultId, type, count} for rules / spells / items / characters; resolve via the matching vault_get_* tool by type). Pair with imagine_list_adventure_pages to locate the id first.
Inputs: id (required), raw. Returns: object
imagine_get_adventure_pagesGet many adventure pages at onceARead-onlyIdempotentInspect
Batch read of adventure pages by id (up to 50 per call). Use this when you need to walk an act and read several scenes' bodies — one call instead of one tool invocation per page. Each returned page carries the same shape imagine_get_adventure_page produces (full markdown body, ancestors, prev/next sibling navigation, expanded shortcodes by default). The response is { pages: [...], missing: [...] }; ids the caller can't view, or that don't exist, land silently in missing rather than failing the whole batch.
Inputs: ids (required), raw. Returns: object
imagine_get_adventure_recapsGet the session recaps for an adventureARead-onlyIdempotentInspect
Fetch the play-session recaps written while running this adventure, grouped by linked play campaign. Each campaign entry carries the sessions tagged with this adventure (via the session's imagineAdventureId) in date order, and each session carries its player-recap pages (author + markdown body). Read-through to play: the caller must be a member (the owner or any accepted seat, watchers included) of a linked campaign, or an admin with Admin Mode on, to read its sessions — on a PRIVATE adventure this is the recaps-only path. Members see public recaps plus their own private ones; an admin with Admin Mode on sees every recap. Campaigns with no tagged sessions are omitted. Returns { campaigns: [] } when the adventure has no linked campaigns or nothing is visible to the caller. This replaces the manual walk of play_list_campaign_sessions + play_list_pages per session.
Inputs: id (required). Returns: object
imagine_get_worldGet an imagine worldARead-onlyIdempotentInspect
Fetch one world by id with its settings, membership, and any user-linked play campaigns. The campaign link is informational only and is not auto-synced. Caller must have at least 'view' access to the world.
Inputs: id (required). Returns: object
imagine_get_world_pageGet a world pageARead-onlyIdempotentInspect
Fetch one world page by id with its full markdown body, tags, and parent reference. By default the gateway dereferences bracketed shortcodes (tag-, child-, rule-*) and inlines a compact <expansion> block right after each literal so the LLM has the resolved content alongside what the author wrote. The original literal is preserved. Pass raw: true to skip expansion (useful when round-tripping the body back through imagine_update_world_page). Cross-references in the response: parent (another world page, resolve via imagine_get_world_page) and vaultCharacterId (vault character, resolve via vault_get_character). Pair with imagine_list_world_pages or imagine_search_world_pages to locate the id first.
Inputs: id (required), raw. Returns: object
imagine_hide_world_stockHide a stock rule, spell, or item in a WorldAIdempotentInspect
Hide a stock vault rule, spell, or item in a World: a Character in the World is no longer offered it in vault's pickers, character creation, or level-up, unless another World the Character is in does not hide it. Nothing is taken off any sheet; a Character that holds the record keeps it, and adding it by id still works. Hiding a record the World had added as a house rule takes it off the World's house rules and its linked campaigns. Stock records only (400 otherwise). Hiding a record already hidden changes nothing. Returns { hidden: { entityType, entityId, ruleset }, warning }; warning is set when the record could not be taken off every linked campaign. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.
Inputs: id (required), entityId (required), entityType (required). Returns: object
imagine_link_adventure_to_campaignLink a play campaign to an adventureAInspect
Add a play campaign to an adventure's playCampaignIds[], the one stored copy of the link. The campaign's imagineAdventures[] on play_get_campaign lists the adventure from it, which backs the session Adventure tag (imagineAdventureId on play_update_session). The caller must be the campaign's owner or gamemaster (403 otherwise; 404 for an unknown campaign) and have 'edit' access on the adventure. The controller returns 400 if the link already exists; call this only when you've confirmed the link isn't already present (or be ready to handle the 400). Use play_list_my_campaigns to locate the campaign id first.
Inputs: id (required), campaignId (required). Returns: object
imagine_link_world_to_campaignLink a play campaign to a worldAInspect
Link a play campaign to a world. The link is stored once, in the world's playCampaignIds[]; the campaign's imagineWorldIds on play_get_campaign is read from it. Linking also shares house rules between the world and the campaign (each side's house-rule associations are added to the other). The caller must be the campaign's owner or gamemaster (403 otherwise; 404 for an unknown campaign). Every Character on the campaign's roster joins the World (players' Characters and the GM's NPCs and monsters alike), and a Character attached to the campaign later joins it too; the answer carries joined (how many joined), notJoined ([{ characterId, name }], the ones already in as many Worlds as a Character may be, left as they are), and warning (null, or a sentence to relay to the user: it names the Characters that could not join, and also says so when the house-rule sharing could not finish, so it can be set while notJoined is empty). By default also imports the campaign's existing characters as world-page character refs (set importCharacters: false to skip the page import; the Characters still join the World). Returns 400 if the link already exists, so call this only when you've confirmed the link isn't already present (or be ready to handle the 400). Caller must have 'edit' access on the world.
Inputs: id (required), campaignId (required), importCharacters. Returns: object
imagine_list_adventure_pagesList pages in an adventureARead-onlyIdempotentInspect
List pages belonging to one adventure. Returns a tree-friendly summary per page (id, name, link, documentType, parent, menuOrder, locationKey, summary, image). Optional narrowing filters: parent (only direct children of that page — useful for an 'open this act' workflow), documentType (only pages of that type — useful for 'list every scene'). Both filters are combinable. Pair with imagine_get_adventure_page (single) or imagine_get_adventure_pages (batch) for full bodies.
Inputs: id (required), parent, documentType. Returns: object
imagine_list_adventure_partsList the parts of a series adventureARead-onlyIdempotentInspect
List the active parts (child adventures) of a series parent, ordered by menuOrder then name. Adventures can be grouped one level deep: an umbrella adventure (the campaign arc) with full adventures as its parts. Returns slim catalog-card fields per part (id, name, summary, image, ruleset, level, status, stock, link, version, parent, menuOrder). Parts the caller can't view are silently omitted. Returns an empty list for adventures that aren't a series parent. To make an adventure a part, set parent via imagine_update_adventure.
Inputs: id (required). Returns: object
imagine_list_my_adventuresList my adventuresARead-onlyIdempotentInspect
List the adventures the calling user owns or has access to. Returns slim catalog-card fields per adventure (id, name, summary, image, ruleset, level, status, stock, link, version, createdAt, updatedAt, parent, menuOrder). A non-null parent marks the adventure as one part of a series — see imagine_list_adventure_parts. To read a specific adventure's full body and configuration, call imagine_get_adventure with the id.
Inputs: no named parameters. Returns: object
imagine_list_my_worldsList my imagine worldsARead-onlyIdempotentInspect
List the worlds the calling user owns or has access to via membership. Returns slim catalog-card fields per world (id, name, summary, image, link, createdAt, updatedAt). To read a specific world's full body and configuration, call imagine_get_world with the id.
Inputs: no named parameters. Returns: object
imagine_list_world_charactersList a World's CharactersARead-onlyIdempotentInspect
List the vault Characters in a World (any type, monsters included), by name unless sorted, one page at a time. Returns { results, pagination }: each result is { _id, name, image, type, ruleset, owner, group } (owner carries public display fields only; group is monster for a monster, npc for a Character flagged an NPC on its row in a campaign linked to the World, else pc), and pagination is { count, limit, skip }; walk further pages with skip. Only someone who manages the World (whoever may edit it, or a contributor of it) may list them: the app answers 403 to anyone else, and 404 for an unknown or deleted World. Add or remove a Character with imagine_add_character_to_world / imagine_remove_character_from_world; vault_list_character_worlds lists one Character's Worlds.
Inputs: id (required), name, skip, sort, +1 more. Returns: results, pagination
imagine_list_world_house_rulesList a World's house rules, hidden stock, extra skills, and extra damage typesARead-onlyIdempotentInspect
Read a World's house ruleset in one call. Returns houseRuleAssociations ({ world, campaigns, combined }: the rules, spells, and items the World adds as house rules, those its linked campaigns add, and the two merged, each row naming its entityType, entityId, and the contexts that add it), hidden (the stock records the World hides, [{ _id, name, type, ruleset, entityType }]), and houseSkills (the World's extra skills, [{ _id, ruleset, name, attribute, description }]), and houseDamageTypes (the World's extra damage types, [{ _id, ruleset, name }]). A Character in the World is offered stock content plus what its Worlds add, less the stock every one of its Worlds hides, gets the extra skills of its ruleset, and is offered the extra damage types of its ruleset in its sheet's damage line and damage type list editors. Only the World's owner, a contributor, or an admin with Admin Mode on may read this (403 otherwise).
Inputs: id (required). Returns: object
imagine_list_world_pagesList pages in a worldARead-onlyIdempotentInspect
List all pages belonging to one world. Returns a tree-friendly summary (id, name, link, parentId, tags). Pair with imagine_get_world_page to fetch full content.
Inputs: worldId (required). Returns: object
imagine_list_world_pages_by_tagsList world pages by tagsARead-onlyIdempotentInspect
Filter pages within a world by one or more tags. The page's documentType is concatenated into the same keyword set imagine searches, so a tag query of 'character' also matches every page with documentType=character. Use mode='and' to require every tag; mode='or' (default) returns pages matching any tag. Common patterns: all NPCs (tag='npc'), all locations (tag='location'), every character-type page (tag='character').
Inputs: tags (required), worldId (required), mode. Returns: object
imagine_remove_character_from_worldRemove a Character from a WorldAIdempotentInspect
Take a vault Character out of a World. Nothing else on the sheet changes: skills, rules, spells, and items the Character got while in the World stay. Allowed for whoever may edit the Character, edit the World, or is a contributor of the World (403 otherwise). Removing a Character that is not in the World answers 404 and changes nothing. Returns { characterId, worlds: [{ _id, name, link }], updatedAt }: the Worlds the Character is still in and its updatedAt (adopt it for a following vault_update_character).
Inputs: id (required), characterId (required). Returns: object
imagine_remove_world_damage_typeRemove an extra damage type from a WorldADestructiveIdempotentInspect
Remove one of a World's extra damage types. A damage line or a Monster's list that already names it keeps it as typed. Returns { success: true }; 404 for an unknown damage type. Only the World's owner, a contributor, or an admin with Admin Mode on may do this. Destructive. Confirm with the user first.
Inputs: id (required), typeId (required). Returns: object
imagine_remove_world_house_ruleRemove a rule, spell, or item from a World's house rulesADestructiveIdempotentInspect
Take a rule, spell, or item off a World's house rules, and off the linked campaigns that have it from the World. Characters that already hold it keep it. The app answers 400 when the record is not one of the World's own house rules (one a linked campaign adds is removed on that campaign). Caller must be able to edit the World (its owner, a contributor, or an admin with Admin Mode on). Destructive. Confirm with the user first.
Inputs: id (required), entityId (required), entityType (required). Returns: object
imagine_remove_world_skillRemove an extra skill from a WorldADestructiveIdempotentInspect
Remove one of a World's extra skills. Skill rows Characters already have stay on their sheets. Returns { success: true }; 404 for an unknown skill. Only the World's owner, a contributor, or an admin with Admin Mode on may do this. Destructive. Confirm with the user first.
Inputs: id (required), skillId (required). Returns: object
imagine_replace_in_adventure_pageReplace text inside one adventure pageAIdempotentInspect
Surgical find-and-replace inside one adventure page's content. Every byte outside the matched ranges is preserved exactly, so this is the safe primitive for terminology passes (e.g. renaming a monster across a page) where imagine_update_adventure_page's whole-body replace would risk dropping formatting whitespace the LLM can't see in JSON. find matches literally (no regex). All occurrences are replaced in a single pass. Optional expectedOccurrences is a staleness guard — when set, a count mismatch returns 409 with no save instead of silently doing a partial edit. Returns { adventurePage, occurrences }.
Inputs: id (required), find (required), replace (required), expectedOccurrences. Returns: object
imagine_search_public_worldsSearch public Worlds by nameARead-onlyIdempotentInspect
Find public Worlds by name, to add a Character to or to choose when building a Character with vault_build_pc. Returns up to 20 public, active Worlds whose name contains the text, by name, each { _id, name, summary, image, link }. Worlds the caller owns or holds a role on are left out (imagine_list_my_worlds lists those). Fewer than two characters of text returns an empty list.
Inputs: query (required). Returns: object
imagine_search_world_pagesSearch world pages by textARead-onlyIdempotentInspect
Text search over page titles and raw markdown bodies within one world. Returns ranked summary results. Bracketed shortcodes (e.g. [[tag-card:goblin]]) match as literal text, not by the resolved content of the referenced entity, so this tool can miss content the human sees rendered. For category lookups (NPCs, locations, monsters), prefer imagine_list_world_pages_by_tags with the tag or documentType value.
Inputs: query (required), worldId (required). Returns: object
imagine_translate_shorenTranslate to ShorenARead-onlyIdempotentInspect
Translate English text into the Shoren tongue of the world Veylantia — clipped and consonant-struck. Deterministic: the same input always yields the same Shoren. Mark the verb with asterisks (I ran home) to move it to the end, the Shoren way. Returns { translation }.
Inputs: text (required). Returns: object
imagine_unhide_world_stockUnhide a stock rule, spell, or item in a WorldAIdempotentInspect
Stop hiding a stock record in a World, so its Characters are offered it again. Unhiding a record the World does not hide changes nothing. Returns { success: true }. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.
Inputs: id (required), entityId (required), entityType (required). Returns: object
imagine_unlink_adventure_from_campaignUnlink a play campaign from an adventureAIdempotentInspect
Remove a play campaign from an adventure's playCampaignIds[]. Inverse of imagine_link_adventure_to_campaign; the adventure drops out of the campaign's imagineAdventures[] (session tags are left in place — inert while unlinked, re-lit on re-link). A link to a campaign that no longer exists is still removed. Caller must be the campaign's owner or gamemaster and have 'edit' access on the adventure.
Inputs: id (required), campaignId (required). Returns: object
imagine_unlink_world_from_campaignUnlink a play campaign from a worldAIdempotentInspect
Unlink a play campaign from a world: removes the campaign from the world's playCampaignIds[]. Pass removeSyncedHouseRules: true to also remove the house rules the link shared between the world and the campaign. Unlinking takes no Character out of the World. The caller must be the campaign's owner or gamemaster. Caller must have 'edit' access on the world.
Inputs: id (required), campaignId (required), removeSyncedHouseRules. Returns: object
imagine_update_adventureUpdate an adventureAIdempotentInspect
PUT updates to one adventure by id. Only supplied fields are sent. Caller must have 'edit' on the adventure. Series grouping: set parent to group this adventure as one part of an umbrella adventure (depth-1 only — see the field description for the validation rules and the append-to-end ordering default); pass parent: null to ungroup. Linked play campaigns list the adventure under its current name, so a rename shows on them immediately. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_adventure read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), link, name, +20 more. Returns: object
imagine_update_adventure_pageUpdate an adventure pageAIdempotentInspect
PUT updates to one adventure page by id. Only supplied fields are sent; every field on the AdventurePage shape (name, content, summary, image, documentType, tags, parentId, link, menuOrder, aliases, details, worldPageRefs, vaultRefs, treasureRefs, scene-shape goal/duration, location-shape locationKey/map/mapPin) can be updated through this tool. Read-aloud / moving-on / tactics are NOT fields — author them inline in content as [[read-aloud]] / [[moving-on]] / [[tactics]] callout blocks. Caller must have 'edit'. WARNING about content: imagine REPLACES the body with whatever you send. To fix wording inside an existing body without losing formatting whitespace, prefer imagine_replace_in_adventure_page (surgical). To append, fetch the page first with imagine_get_adventure_page (raw=true), concatenate, and send the combined body back. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_adventure_page read of this page; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written — writing from memory of an earlier read is not possible.
Inputs: id (required), baseUpdatedAt (required), map, goal, +21 more. Returns: object
imagine_update_worldUpdate an imagine worldAIdempotentInspect
PUT updates to one world by id. Caller must have 'edit' access (the owner, a contributor, or an admin with Admin Mode on). showInvite changes only for the world's owner or an admin with Admin Mode on; from a contributor it is ignored. Only supplied fields are sent; imagine merges them onto the existing document. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_world read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), link, menu, +13 more. Returns: object
imagine_update_world_pageUpdate a world pageAIdempotentInspect
PUT updates to one world page by id. Only supplied fields are sent. Caller must have 'edit' on the world page. Imagine REPLACES the content body with whatever you send. To append, fetch the page first with imagine_get_world_page, concatenate, and send the combined body back. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_world_page read of this page; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written — writing from memory of an earlier read is not possible. Set visibility: 'gm' to make a page GM-only (the world's owner, contributors, and an admin with Admin Mode on only; hidden from and 404 for everyone else), 'masked' to keep it participating in lists/backlinks under maskName with the real identity hidden, or 'public' to reveal it. Hidden pages are stripped from the world menu.
Inputs: id (required), baseUpdatedAt (required), link, name, +25 more. Returns: object
imagine_update_world_skillChange a World's extra skillAIdempotentInspect
Change the name, ability, or description of one of a World's extra skills; only the fields you send change, and the skill keeps its ruleset. Skill rows already on Characters' sheets do not change. Takes no baseUpdatedAt: the app changes only the fields sent. Returns { houseSkill }; 409 when the new name is taken in the skill's ruleset, 404 for an unknown skill. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.
Inputs: id (required), skillId (required), name, attribute, +1 more. Returns: object
list_my_submissionsList my bug reports and requestsARead-onlyIdempotentInspect
List the calling user's own submissions (bug reports and feature requests) with each one's status: new, reviewing, clarification (Embers is waiting on the user), planned, resolved, declined, or closed (read-only, 30 days after resolved or declined).
Inputs: no named parameters. Returns: object
list_rulesetsList allowed rulesetsARead-onlyIdempotentInspect
Return the ruleset codes the calling user is permitted to use across the Embers ecosystem. Includes the always-public rulesets plus any restricted rulesets the user has been granted access to. Use this before populating any ruleset selector or before filtering vault/play/imagine results by ruleset.
Inputs: no named parameters. Returns: object
play_accept_friend_requestAccept a friend requestAIdempotentInspect
Accept a pending friend request directed at the calling user. Pass friendId — the _id of the friend record on the calling user's friends list (from play_list_pending_friends), NOT the requester's user id.
Inputs: friendId (required). Returns: object
play_add_campaign_characterAdd a character to a campaignAInspect
Attach a vault character to a play campaign so the character participates in play. Play places the attachment on the campaign leg matching the vault character's own ruleset — the campaign must have an active leg for that ruleset. Caller must hold a seat at the table (the campaign's owner, or an accepted gamemaster or player) and be able to edit the character (its owner, or an admin with Admin Mode on). A character can be on at most 10 active campaigns (400 for one more). The character also joins every World the campaign is linked to; the answer carries worldsNotJoined ([{ _id, name }], the linked Worlds a character already in as many Worlds as it may be did not join) and warning (a sentence saying so, or null; relay it to the user). Joining a World changes the character itself: the answer's updatedAt is its new version (null when it joined none), the baseUpdatedAt a later vault_update_character needs, and addedSkills lists the skill rows the join added. Use vault_search_characters to locate the character id first.
Inputs: campaignId (required), characterId (required), npc. Returns: object
play_add_campaign_itemAdd an item to a campaign's allowlistAInspect
Add a vault item to a campaign's allowlist. The item always lands on the leg matching the ITEM's own ruleset — the campaign must have a leg for that ruleset or play answers 400. The optional ruleset param never retargets; it only confirms the expected leg, and a mismatch answers 400. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: itemId (required), campaignId (required), ruleset. Returns: object
play_add_campaign_legAdd a ruleset leg to a campaignAInspect
Add a new active leg to a campaign for the given ruleset, letting the same campaign (same sessions, players, and history) also run under that ruleset. The new leg starts empty — no rules, items, spells, or characters; fill it with the add tools. One leg per ruleset: play answers 409 if a leg for this ruleset already exists. Caller must be the campaign owner or an accepted gamemaster; ordinary players get 403.
Inputs: campaignId (required), ruleset. Returns: object
play_add_campaign_ruleAdd a rule to a campaign's allowlistAInspect
Add a vault rule to a campaign's allowlist. The rule always lands on the leg matching the RULE's own ruleset — the campaign must have a leg for that ruleset or play answers 400. The optional ruleset param never retargets; it only confirms the expected leg, and a mismatch answers 400 (e.g. "This rule is X, not Y"). Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: ruleId (required), campaignId (required), ruleset. Returns: object
play_add_campaign_spellAdd a spell to a campaign's allowlistAInspect
Add a vault spell to a campaign's allowlist. The spell always lands on the leg matching the SPELL's own ruleset — the campaign must have a leg for that ruleset or play answers 400. The optional ruleset param never retargets; it only confirms the expected leg, and a mismatch answers 400. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: spellId (required), campaignId (required), ruleset. Returns: object
play_cancel_friend_requestCancel a friend requestADestructiveIdempotentInspect
Cancel a friend request the calling user previously sent. Pass friendId — the _id of the friend record on the calling user's own friends list (the one the caller initiated).
Inputs: friendId (required). Returns: object
play_check_recap_existsCheck if the user already wrote a recap for a sessionARead-onlyIdempotentInspect
Cheap boolean check — returns { exists: boolean } for whether the calling user has an active player-recap page attached to the given session. Use this to gate play_create_page so you don't write a duplicate recap.
Inputs: sessionId (required). Returns: object
play_consume_pbem_emailsLink inbox emails to a moveAInspect
Mark inbox emails consumed and link them to the move they were collated into. Use after play_create_move / play_update_move when building a move from emails. Only 'new' items in the move's campaign are affected. GM-only.
Inputs: moveId (required), itemIds (required). Returns: object
play_create_campaignCreate a play campaignAInspect
Create a new campaign owned by the calling user. Required: name. ruleset becomes the campaign's first leg (campaigns hold ruleset-specific material in per-ruleset legs; add more with play_add_campaign_leg). Play writes only name, summary, description, image, public, hideSections, dismissedSessionZeroNudge, xCardEnabled, showCreatureDetails, and autoRollInitiative at create and ignores any other field; seats come from the invite tools. Creating it public needs Premium, VIP, or admin.
Inputs: name (required), image, public, ruleset, +6 more. Returns: object
play_create_moveCreate a moveAInspect
Record a new play-by-email move on a campaign. Required: campaignId. Optional: name (defaults 'Move '), number (defaults next-in-sequence), date dd/mm/yy (defaults today), description, sessionId (chapter), parentId (child scene; excludes sessionId), playerIds (visibility restriction to listed campaign players). GM-only: caller must be the campaign owner or an accepted gamemaster.
Inputs: campaignId (required), date, name, number, +4 more. Returns: object
play_create_pageCreate a pageAInspect
Create a new page. Required: name. Set documentType: 'player-recap' and ref: { refType: 'session', refId: <sessionId> } to make a session recap — play sends notifications to the other campaign players on recap create. Before creating a recap, call play_check_recap_exists first to avoid duplicates.
Inputs: name (required), ref, link, active, +6 more. Returns: object
play_create_sessionCreate a sessionAInspect
Create a new session for a campaign. Required: campaignId and date (dd/mm/yy format). Other fields (name, description, planned battlemaps) are optional and pass through to play. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: date (required), campaignId (required), name, image, +6 more. Returns: object
play_decline_friend_requestDecline a friend requestADestructiveIdempotentInspect
Decline a pending friend request directed at the calling user. Pass friendId from play_list_pending_friends.
Inputs: friendId (required). Returns: object
play_delete_campaignDelete a play campaignADestructiveIdempotentInspect
Permanently delete a campaign by id. Removes all of its sessions, invites, and members. Caller must be the campaign's owner or an admin with Admin Mode on; a gamemaster cannot delete it. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
play_delete_characterDetach a character from playADestructiveIdempotentInspect
Detach a character from play's tracking. Removes any campaign references but does NOT delete the underlying vault character document. Caller must own the character, be an admin with Admin Mode on, or be the GM of the character's campaign.
Inputs: id (required). Returns: id, deleted
play_delete_moveDelete a moveADestructiveIdempotentInspect
Permanently delete a move by id. Its child moves are detached back into the feed, not deleted. GM-only. Destructive — the move's collated round text is lost. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
play_delete_pageDelete a pageADestructiveIdempotentInspect
Soft-delete a page by id (30-day TTL via deactivated_at, recoverable in the app UI within the window). Allowed for the page's owner, an admin with Admin Mode on, or the GM of the page's campaign for a page the table sees (a public page, or a GM-side page: dm-notes, campaign-logistics). A player's private pages and recaps answer to their author (or an admin with Admin Mode on) alone, and a character's player notes (player-notes) to the character's player (or an admin with Admin Mode on), never the GM. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
play_delete_sessionDelete a sessionADestructiveIdempotentInspect
Permanently delete a session by id, including its notes and any session-image / battlemap attachments. Caller must be the session's owner, an admin with Admin Mode on, or the campaign's GM (its owner or an accepted gamemaster); players get 403. Destructive. Confirm with the user first.
Inputs: id (required). Returns: id, deleted
play_disable_pbem_inboxDisable a campaign's PBEM inboxAIdempotentInspect
Disable the inbox: mail to the campaign's address stops routing (bounces at the webhook). The address is kept and re-enables unchanged. GM-only.
Inputs: campaignId (required). Returns: object
play_dismiss_pbem_emailDismiss a PBEM inbox emailAIdempotentInspect
Mark an inbox email dismissed (misdirected mail, noise). The item is retained with status 'dismissed', not deleted. GM-only.
Inputs: itemId (required). Returns: object
play_enable_pbem_inboxEnable a campaign's PBEM inboxAIdempotentInspect
Enable the play-by-email inbox on a campaign. Mints the campaign's unique inbound address on first enable (subsequent enables keep the existing address). Returns the pbem block including the address players CC. GM-only.
Inputs: campaignId (required). Returns: object
play_find_friendFind a friend by name or emailARead-onlyIdempotentInspect
Search the play user directory by name or email substring. Used to locate a user before sending a friend request. Rate-limited by play to deter scraping.
Inputs: query (required). Returns: object
play_get_campaignGet a play campaignARead-onlyIdempotentInspect
Fetch one campaign by id, including settings and any DM/player metadata. Readable by a participant (the owner, a gamemaster, a player, or a watcher), by anyone when the campaign is public, and by an admin with Admin Mode on. The campaign's ruleset-specific material lives in its legs array — one entry per ruleset, each carrying { ruleset, active, rules, items, spells, characters }; inactive legs are hidden from normal UI but never deleted. There is no campaign-level ruleset field. Defaults to a summary shape: each leg's raw rule/item/spell ObjectId arrays are replaced with resolved [{ _id, name }, ...] lists the LLM can act on. Pass detail: 'full' to receive the raw ObjectId arrays instead. Each leg's rules, items, and spells are the campaign's house rules in that leg's ruleset. The response's imagineWorldIds and imagineAdventures ([{ id, name }, ...], each adventure's current name) list the Imagine worlds and adventures linked to this campaign; they are read from the worlds' and adventures' own links and are read-only here (change them with the imagine link/unlink tools). The imagineAdventures ids are the valid values for a session's imagineAdventureId tag.
Inputs: id (required), detail. Returns: object
play_get_campaign_party_orderGet a campaign's party orderARead-onlyIdempotentInspect
Read a campaign's Party Order: its marching order and its watches. partyOrder.ranks runs front to back (rank 1 is the front); each rank's characters run left to right. partyOrder.watches lists the watches in order, each with the characters assigned to it; a character may stand more than one watch. Characters are vault character ids, the _id of the rows play_list_campaign_characters returns (use it for names). A campaign that has never set one answers one empty rank and three empty watches. Readable by the campaign's GM and accepted players; watchers and pending invitees get 403.
Inputs: campaignId (required). Returns: object
play_get_character_noteGet a character note (DM or player)AIdempotentInspect
Fetch the DM-side or player-side note attached to a play character. Lazy-creates the note on first read if absent, so this endpoint always returns a note. Readable by the character's player (or an admin with Admin Mode on) and the campaign's GM; the DM-side note (dm-notes) is the GM's alone, and anyone else gets 403.
Inputs: characterId (required), documentType (required). Returns: object
play_get_moveGet a moveARead-onlyIdempotentInspect
Fetch one move by id, including its full markdown body, plus a children array of its child scenes (split party) filtered the same way. A restricted move reads as 404 for players not on its list; the GM and an admin with Admin Mode on read every move. Readable by anyone who may view the move's campaign (a participant, anyone when the campaign is public, or an admin with Admin Mode on), and by the move's owner.
Inputs: id (required). Returns: object
play_get_pageGet a pageARead-onlyIdempotentInspect
Fetch one page by id, including its full markdown body. Readable by the page's owner or an admin with Admin Mode on; by the campaign's GM for a GM-side page (GM notes, logistics); and, for a public page, by anyone who may view its campaign (any participant, or anyone when the campaign is public); a public page with no ref (no campaign, session, or character) is readable by anyone. Returns { page, canEdit }; canEdit says whether this caller may update and delete the page. For a character's player notes it is the character's player's answer: the campaign's GM may update player notes through play_update_character_note but never delete them, so the GM gets canEdit: false here.
Inputs: id (required). Returns: object
play_get_sessionGet a sessionARead-onlyIdempotentInspect
Fetch one session by id, including its notes, battlemap references, and session-image attachments. Readable by anyone who may view the session's campaign (a participant, anyone when the campaign is public, or an admin with Admin Mode on), and by the session's owner.
Inputs: id (required). Returns: object
play_invite_campaign_playerInvite a player to a campaignAInspect
Send a campaign invite to another user. Caller must be the campaign's GM (its owner or an accepted gamemaster); players, watchers, and admins get 403. Play rate-limits this endpoint (per-caller and per-campaign) to deter spam.
Inputs: userId (required), campaignId (required), role. Returns: object
play_list_campaign_charactersList characters in a campaignARead-onlyIdempotentInspect
List the characters participating in a play campaign. Returns play-side character refs; pair with vault_get_character for full character data. Defaults to a summary shape (id, name, image, npc flag, short description); pass detail: 'full' to receive each character's full vault sheet inline. Each row's characterOwner is the vault character's own owner; that owner (or an admin with Admin Mode on) edits the sheet with vault_update_character, whoever attached it (owner) does not. Each row's status is its seat's (an inactive seat sits out of the table), and companionIds lists the character's Owned companions, who sit at the table with it.
Inputs: campaignId (required), detail. Returns: object
play_list_campaign_companionsList companions in a campaignARead-onlyIdempotentInspect
List the companions (buddies) attached to a play campaign's characters — the supporting cast a table sees beyond the roster. Read-only; the tie itself is managed on the vault character sheet (vault_attach_companion / vault_detach_companion). Monster-typed companions are excluded server-side. One entry per (Main, companion) pair, so a companion linked by two characters appears twice; each entry carries companionOf: { characterId, name, userId } naming the character it accompanies, canEdit (whether the caller may edit the companion character), canOpenInVault (whether the caller may open it in the vault: its editor, the campaign's GM, or whoever may edit the Main it is tied to), plus display fields (name, type, ruleset, image, description) and a projected primaryToken slice or null. Pair with vault_get_character on companionCharacterId for the companion's full sheet.
Inputs: campaignId (required). Returns: object
play_list_campaign_itemsList items allowed in a campaignARead-onlyIdempotentInspect
List the campaign's house items: the items it holds as active house-rule associations. Subset of the broader vault catalog. Each sits on the leg matching its own ruleset: omit ruleset to list the items across every leg, or set it to scope the list to that one leg.
Inputs: campaignId (required), ruleset. Returns: object
play_list_campaign_movesList moves in a campaignARead-onlyIdempotentInspect
List the play-by-email moves of one campaign — the move feed. Sorted by shelf position (order), newest first by default; pass order: 'asc' for reading order. Defaults to a summary shape: each move's description is a ~240-character prose preview (image URLs and [[...]] markers don't count toward the budget) carrying a descriptionTruncated flag; detail: 'full' returns complete bodies. Child moves (split-party scenes) are excluded unless children: true. Restricted moves are server-filtered: players see only moves they're listed on; the GM and an admin with Admin Mode on see all. Readable by anyone who may view the campaign (a participant, anyone when the campaign is public, or an admin with Admin Mode on).
Inputs: campaignId (required), limit, order, detail, +1 more. Returns: object
play_list_campaign_playersList players in a campaignARead-onlyIdempotentInspect
List the players in a play campaign with their roles, invite status, and any per-player flags.
Inputs: campaignId (required). Returns: object
play_list_campaign_rulesList rules allowed in a campaignARead-onlyIdempotentInspect
List the campaign's house rules: the rules it holds as active house-rule associations. Subset of the broader vault catalog. Each sits on the leg matching its own ruleset: omit ruleset to list the rules across every leg, or set it to scope the list to that one leg.
Inputs: campaignId (required), ruleset. Returns: object
play_list_campaign_sessionsList sessions in a campaignARead-onlyIdempotentInspect
List sessions belonging to one campaign. Readable by anyone who may view the campaign (a participant, anyone when the campaign is public, or an admin with Admin Mode on). Defaults to a compact summary shape ordered by most-recently-updated; pass detail: 'full' for the populated shape.
Inputs: campaignId (required), sort, limit, detail. Returns: object
play_list_campaign_spellsList spells allowed in a campaignARead-onlyIdempotentInspect
List the campaign's house spells: the spells it holds as active house-rule associations. Subset of the broader vault catalog. Each sits on the leg matching its own ruleset: omit ruleset to list the spells across every leg, or set it to scope the list to that one leg.
Inputs: campaignId (required), ruleset. Returns: object
play_list_joinable_campaignsList campaigns a new Character can joinARead-onlyIdempotentInspect
List the campaigns a new Character of the given ruleset can join, as the app decides it: a bare array [{ _id, name }]. These are the campaigns to offer when building a Character with vault_get_pc_creation_options / vault_build_pc (campaignIds). A ruleset this account may not use returns an empty list.
Inputs: ruleset. Returns: object
play_list_my_campaignsList campaigns I runARead-onlyIdempotentInspect
List campaigns where the calling user is the DM/owner. Each campaign's ruleset-specific material lives in its legs array — one entry per ruleset, each carrying { ruleset, active, ... }; there is no campaign-level ruleset field. Defaults to a compact summary shape: identification fields, counts of rules/items/spells/sessions/players/characters, and the character roster (playId + vaultId pairs). Pass detail: 'full' to receive the full campaign documents (raw ObjectId arrays for the legs' allowlists, full descriptions, X-card history).
Inputs: detail. Returns: object
play_list_my_charactersList my play charactersARead-onlyIdempotentInspect
List the characters the calling user has in any of their campaigns (DM or player). For a single character's full sheet data, use vault_get_character with the returned id.
Inputs: no named parameters. Returns: object
play_list_my_friendsList my friendsARead-onlyIdempotentInspect
List the calling user's accepted friends. Returns each friend's display name and id, suitable for campaign-invite or friend-lookup workflows.
Inputs: no named parameters. Returns: object
play_list_my_sessionsList my sessionsARead-onlyIdempotentInspect
List sessions the calling user is part of across all their campaigns (DM or player). Defaults to a compact summary shape ordered by most-recently-updated. Pass detail: 'full' to receive the populated session document (battlemap refs, full description). Use limit to cap the array size.
Inputs: sort, limit, detail. Returns: object
play_list_pagesList play pagesARead-onlyIdempotentInspect
List play pages, optionally filtered by what they're attached to and/or by documentType. To find session recaps, pass refType: 'session', refId: '<sessionId>', documentType: 'player-recap'. Defaults to a compact summary shape; pass detail: 'full' for the page body markdown inline. Returns the pages the caller may read: public pages of campaigns they may view, public pages with no ref, their own pages, and, when refId scopes the list to one record, that campaign's GM-side pages (dm-notes, campaign-logistics) for its GM. An admin with Admin Mode on gets every page.
Inputs: refId, detail, refType, documentType. Returns: object
play_list_participated_campaignsList campaigns I play inARead-onlyIdempotentInspect
List campaigns where the calling user is a player (not the DM). Each campaign's ruleset-specific material lives in its legs array — one entry per ruleset, each carrying { ruleset, active, ... }; there is no campaign-level ruleset field. Pair with play_list_my_campaigns for a complete view of the user's campaign involvement.
Inputs: no named parameters. Returns: object
play_list_pbem_inboxList a campaign's PBEM inboxARead-onlyIdempotentInspect
List the captured inbound emails on a play-by-email campaign. Each item carries the matched player (or null when unmatched), sender display name, sent time, subject, verbatim body, a distilled replyText (latest contribution with quoted history stripped), senderIsGamemaster (true when the sender is the campaign owner or an accepted gamemaster — the move builder boxes GM emails), and senderDisplayName (the GM-set attribution name for the matched player, empty when unset). GM-only.
Inputs: campaignId (required), status. Returns: object
play_list_pending_friendsList pending friend requestsARead-onlyIdempotentInspect
List friend requests directed at the calling user that have not yet been accepted or declined.
Inputs: no named parameters. Returns: object
play_list_session_movesList a chapter's movesARead-onlyIdempotentInspect
List the moves grouped under one session (a play-by-email 'chapter'), in reading order with full bodies by default; detail: 'summary' trims each description to a ~240-character prose preview with a descriptionTruncated flag. Restricted moves are server-filtered: players see only moves they're listed on; the GM and an admin with Admin Mode on see all. Readable by anyone who may view the session's campaign (a participant, anyone when the campaign is public, or an admin with Admin Mode on), and by the session's owner.
Inputs: sessionId (required), detail. Returns: object
play_list_user_pagesList pages authored by a userARead-onlyIdempotentInspect
List the pages a given user has authored. Pass own user id (from whoami) to see private pages too; for another user, only their public pages that the caller may read come back (pages of campaigns the caller may view, or with no ref). Defaults to summary shape.
Inputs: userId (required), detail. Returns: object
play_regenerate_pbem_addressRegenerate a campaign's inbound addressADestructiveIdempotentInspect
Mint a fresh inbound address for the campaign (leak recovery). The old address stops routing IMMEDIATELY and every player must switch to the new one — confirm with the user first. GM-only.
Inputs: campaignId (required). Returns: object
play_remove_campaign_itemRemove an item from a campaign's allowlistADestructiveIdempotentInspect
Remove a vault item from a campaign's allowlist. Removal targets the leg matching the ITEM's own ruleset; the optional ruleset param only confirms that leg (mismatch answers 400), never retargets. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: itemId (required), campaignId (required), ruleset. Returns: object
play_remove_campaign_playerRemove a player from a campaignADestructiveIdempotentInspect
Remove a player from a campaign. Caller must be the campaign's GM (its owner or an accepted gamemaster). The campaign owner cannot be removed. playerId is the player-record id returned by play_list_campaign_players (the embedded player doc id, NOT the user's id).
Inputs: playerId (required), campaignId (required). Returns: object
play_remove_campaign_ruleRemove a rule from a campaign's allowlistADestructiveIdempotentInspect
Remove a vault rule from a campaign's allowlist. Removal targets the leg matching the RULE's own ruleset; the optional ruleset param only confirms that leg (mismatch answers 400), never retargets. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: ruleId (required), campaignId (required), ruleset. Returns: object
play_remove_campaign_spellRemove a spell from a campaign's allowlistADestructiveIdempotentInspect
Remove a vault spell from a campaign's allowlist. Removal targets the leg matching the SPELL's own ruleset; the optional ruleset param only confirms that leg (mismatch answers 400), never retargets. Caller must be the campaign's owner, a gamemaster or player with an accepted seat (watchers excluded), or an admin with Admin Mode on.
Inputs: spellId (required), campaignId (required), ruleset. Returns: object
play_remove_friendRemove a friendADestructiveIdempotentInspect
Remove an existing friend connection. Pass friendId from play_list_my_friends. Destructive on the social graph; both sides lose the connection.
Inputs: friendId (required). Returns: object
play_resolve_pbem_emailAssign an unmatched email to a playerAIdempotentInspect
Resolve an unmatched inbox email to an accepted campaign member. Pass remember: true to auto-match future emails from the same sender address (stored as an HMAC key, never the address). GM-only.
Inputs: itemId (required), playerId (required), remember. Returns: object
play_respond_to_campaign_inviteAccept or decline a campaign inviteAInspect
Respond to a pending campaign invite directed at the calling user. The campaign id is the campaign the invite belongs to; accept decides yes/no.
Inputs: accept (required), campaignId (required). Returns: object
play_send_friend_requestSend a friend requestAIdempotentInspect
Send a friend request to another user. Pass targetUserId (the recipient's User _id) — use play_find_friend to look them up first.
Inputs: targetUserId (required). Returns: object
play_set_campaign_leg_activeActivate or deactivate a campaign legAIdempotentInspect
Toggle a campaign leg's active flag by ruleset. Deactivating hides the leg from normal UI (the campaign stops appearing to viewers whose active ruleset matches it) but never deletes it — all of its content and attachments survive and reactivating restores them. Play refuses to deactivate the last active leg (400). Caller must be the campaign owner or an accepted gamemaster; ordinary players get 403.
Inputs: active (required), campaignId (required), ruleset. Returns: object
play_set_campaign_player_roleChange a campaign player's roleADestructiveIdempotentInspect
Change the role of a seat in a campaign, accepted or still a pending invite. Caller must be the campaign's GM (its owner or an accepted gamemaster). The campaign owner's role cannot be changed, and a caller cannot change their own. playerId is the player-record id returned by play_list_campaign_players (the embedded player doc id, NOT the user's id).
Inputs: role (required), playerId (required), campaignId (required). Returns: object
play_set_pbem_display_nameSet a player's PBEM attribution nameAIdempotentInspect
Set the name a campaign member's emails are attributed to when collated into a move (e.g. the character they play). Applies to all of that player's emails; blank clears it back to their Embers name. GM-only.
Inputs: playerId (required), campaignId (required), displayName (required). Returns: object
play_update_campaignUpdate a play campaignAIdempotentInspect
PUT updates to one campaign by id. Caller must be the campaign's owner, an admin with Admin Mode on, or the campaign's GM (an accepted gamemaster). Play writes only name, summary, description, image, public, hideSections, dismissedSessionZeroNudge, xCardEnabled, showCreatureDetails, and autoRollInitiative, plus active for the owner or an admin with Admin Mode on, and ignores any other field; seats change only through the invite tools; making the campaign public needs Premium, VIP, or admin. Only supplied fields are sent. legs is NOT writable here (it is stripped): add a leg with play_add_campaign_leg, toggle one with play_set_campaign_leg_active, and change a leg's contents with the add/remove rule/item/spell/character tools. REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_campaign read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), name, image, +8 more. Returns: object
play_update_campaign_party_orderChange a campaign's party orderAInspect
Make one change to a campaign's Party Order (marching order or watches) and get the saved order back in the play_get_campaign_party_order shape. One op per call; make several calls for several changes. Ranks, positions, and watches are numbered from 1. A character must be in the campaign (any seat, active or inactive) to be placed or assigned. Caller must be the campaign's GM or an accepted player; watchers and pending invitees get 403.
Inputs: op (required), campaignId (required), rank, count, +4 more. Returns: object
play_update_character_noteUpdate a character note (DM or player)AIdempotentInspect
Update the DM-side or player-side note attached to a play character. PUT semantics — description replaces the current body. The player-side note (player-notes) is updated by the character's player (or an admin with Admin Mode on) or the campaign's GM; the DM-side note (dm-notes) by the campaign's GM alone, and a player gets 403. Triggers a notification (to the character owner if a GM updated, to GMs if a player updated). REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_character_note read of the same note; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: characterId (required), description (required), documentType (required), baseUpdatedAt (required), +1 more. Returns: object
play_update_moveUpdate a moveAIdempotentInspect
Update a move by id: name, description, number (game label), date, order (shelf position), sessionId (chapter; null detaches), parentId (child scene; null detaches; setting it clears the chapter), or playerIds (visibility; [] reopens to everyone). Only supplied fields are sent. GM-only. REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_move read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), date, name, +6 more. Returns: object
play_update_pageUpdate a pageAIdempotentInspect
Update a page by id. PUT semantics — supplied fields replace their current values. To append to a recap body, fetch first via play_get_page, concatenate, and send back. Allowed for the page's owner, an admin with Admin Mode on, or the GM of the page's campaign for a page the table sees (a public page, or a GM-side page: dm-notes, campaign-logistics); a player's private pages and recaps answer to their author (or an admin with Admin Mode on) alone. REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_page read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written — writing from memory of an earlier read is not possible.
Inputs: id (required), baseUpdatedAt (required), ref, link, +8 more. Returns: object
play_update_sessionUpdate a sessionAIdempotentInspect
Update a session by id. Use this to append session notes, change the date, rename, or tag the session with the Imagine adventure it belongs to (imagineAdventureId — valid ids come from the campaign's imagineAdventures list on play_get_campaign; null untags). Only the fields you supply are sent. Caller must be the session's owner, an admin with Admin Mode on, or the campaign's GM (its owner or an accepted gamemaster); players get 403. REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_session read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), date, name, +11 more. Returns: object
reply_to_submissionReply on one of my submissionsAInspect
Post a reply on one of the calling user's submissions, for example to answer a clarification question from Embers. Pass submissionId and text; optional attachments are ids from upload_submission_screenshot. The original report cannot be edited, and a closed submission takes no replies.
Inputs: submissionId (required), text, attachments. Returns: object
upload_submission_screenshotUpload a screenshot for a submissionAInspect
Upload one screenshot to attach to a bug report, request, or reply. Pass mimeType and the base64 data. Returns { id, url }; pass the id in attachments on create_submission or reply_to_submission.
Inputs: data (required), mimeType (required). Returns: object
vault_attach_companionAttach a companion to a characterAInspect
Attach a buddy (animal companion, hireling, follower, granted NPC, stock monster) to a Main character the user may edit (their own, or any for an admin with Admin Mode on). The row appears in the sheet's Companions section. Mode is decided by ownership: 'owned' for a character the Main character's owner already owns (its values are then edited on its own document via vault_update_character — the row is a live window, no copy is made, no character slot is used); 'link' for a character someone else owns (the source is never written; track its hit points and uses via vault_update_companion_state). The same source may be attached more than once — each row is independent. Response is { companion, companions, updatedAt }; ADOPT the returned updatedAt as the Main character's fresh stamp for any follow-up write.
Inputs: id (required), mode (required), characterId (required). Returns: object
vault_build_monsterBuild a monsterAInspect
Create a complete monster character in one call, in a ruleset the monster builder supports (the ruleset field's list; list_rulesets gives each code's label). Replaces the vault_create_character + multiple vault_update_character pattern for monster authoring — fully typed input schema, so structured fields cannot be silently stringified. Caller passes source-text values (final AC, skill bonuses, attack bonuses); vault computes the stored base values, derives proficient / expertise / misc flags, formats spell-list markdown, creates recharge trackables, generates the challenge, legendary-intro, and alternate-form speed notes. Sets type: 'monster', settings.autoPassiveBonuses: false, and the derived core.experience automatically. The authoring guide at vault_get_authoring_guide({ rulesetCode: <the monster's ruleset>, entityType: 'monster' }) documents every field's source-text meaning and is the conventions reference for what shape to send. Returns the created character document.
Inputs: ac (required), cr (required), hp (required), name (required), +27 more. Returns: object
vault_build_pcBuild a player characterAInspect
Assemble a complete, playable player character in one call from a flat draft of choices, in a ruleset with guided creation (the ruleset field's list). Vault validates every pick against the user's own + stock content and the chosen campaigns' and Worlds' content, and builds the full sheet — ability scores (with background bump), skills, saves, hit points, starting equipment + derived weapon actions, granted rules / feats / abilities, trackables, and a creation-recap note. Read vault_get_pc_creation_options first to get legal ids and pools. Required: name, classRuleId, abilityScoreMethod, abilityScoreAssignments, skillProficiencies, toolProficiencies, and the equipment picks (startingEquipmentLabel for options without a set; startingEquipmentSetLabels where the class's options carry a set). What a ruleset asks for differs and the options and constants say which applies: a ruleset whose constants list no background bump modes and whose backgrounds carry no feat takes no background bump or background feat, gives ability score increases through the heritage rule and its subrace (fixed ones need no pick; chosen ones go in abilityBumpPicks keyed by that rule's _id), offers the roll method (abilityScoreRolls), and takes backgroundToolProficiencies, the background equipment picks, backgroundAbilityChoices, and skillReplacements / toolReplacements; where its class option carries startingGold dice it may take startingGold with startingGoldRolls in place of every equipment pick. Required when present: backgroundFeatRuleId (an open featOpen background's feat, from the originFeatCategory feats — the build rejects the draft without it). Optional: speciesRuleId, backgroundRuleId, backgroundSkillProficiencies (when the background grants skills as a choice), the background bump (backgroundBumpMode + backgroundBumpAssignments), backgroundFeatRuleId (as a swap on a fixed-feat background), languages, languageChoicePicks (background/species language-choice grants), alignment, description/image/appearances/token, and the choice maps (proficiencyChoicePicks, abilityChoices, speciesAbilityChoices, backgroundFeatChoices, equipmentChoices, weaponAbilityChoices, abilityBumpPicks) plus the spell maps (spellChoicePicks, spellListChoicePicks, preparedSpellPicks, castingAbilityPicks) for spellcasters / spell-list-choice grants. proficiencyChoicePicks and spellChoicePicks are keyed ":" and only needed where a grant's count is smaller than its option pool. castingAbilityPicks is required for any spellChoices block surfacing castingAbilityOptions — the projection only surfaces that array when a pick is genuinely needed (a spellListChoices block's ability pick rides its spellListChoicePicks entry as castingAbility instead). The projected spellChoices/spellListChoices arrays may hold null entries (blocks inert at the starting level) — count them when keying picks by index. A feat chosen via an ability's ruleChoice (in abilityChoices/speciesAbilityChoices) brings its own sub-choices — supply them in those same maps keyed by the picked feat's _id. A repeatable feat filling the background slot (backgroundFeatRuleId) instead prefixes its pick keys bg:<featId>. When the background option carries a non-null featSpellList, its own feat's spell-list pick must use that list. Campaigns and Worlds: pass the same campaignIds and worldIds the options were read with (none means stock plus the user's own content only). The character joins each chosen campaign and World when it is built and gets the chosen Worlds' extra skills as skill rows; a choice that can no longer be joined fails the build with CREATION_CONTEXT_LOST, naming it and the reason, and nothing is created. The created character is owned by the calling user and returned in full. On an invalid draft vault returns the specific reason (e.g. a pick out of pool, a wrong pick count, a missing required choice) as a tool error — fix the draft and retry.
Inputs: name (required), ruleset (required), classRuleId (required), toolProficiencies (required), +42 more. Returns: object
vault_clone_characterClone a vault characterAInspect
Duplicate any vault character the calling user can see — their own characters, stock template content, and other users' authored characters are all valid sources. The server does the deep-copy (stats, skills, items, rules, spells, trackables, all of it) — caller passes only the source id and optionally a new name. The new character is owned by the caller (not the source's original owner) and counts against the caller's character entitlement limit. When name is omitted, the clone is named <source name> (Copy). Use this instead of fetching the source sheet and re-POSTing it via vault_create_character.
Inputs: id (required), name. Returns: object
vault_convert_characterConvert a character to its ruleset's successorAInspect
Make the version of a character in the ruleset that succeeds its own (the preview's ruleset.to), as its linked sheet there, owned by the original's owner (it counts against the owner's character limit unless a blank linked sheet is being filled in). The original is not changed. Call vault_preview_character_conversion first, show the user its report, and convert only when they agree: pass updatedAt from the preview's character.updatedAt. Vault makes the plan again from the stored character, so the result is what the preview forecast. The new character arrives fully rested, keeps the original's gear, numbers, settings, and notes, and carries the conversion's report as a note. Returns the new character document with _conversionReport, the same shape as the preview's report: what was converted, the choices vault made, what is not in the newer ruleset and was kept, what was carried as is, what was left behind, what was not added, the totals that come out different, and anything that failed (a campaign seat that could not be made; the character still exists). Show the user that report as vault gives it, each row as its name, then its text, then its note; do not compose one. Vault answers 409 when the character changed since the preview (preview again) or already has a used linked sheet in that ruleset, 403 for the character limit or the ruleset, and 404 for an unknown character or one the user may not edit. A conversion that fails leaves nothing behind. A 500 here is a fault in vault's own content that this character's conversion ran into; trying again will not fix it, so tell the user it needs reporting.
Inputs: id (required), updatedAt (required). Returns: object
vault_create_characterCreate a vault characterAInspect
Create a new character in the user's vault. Requires name and ruleset. The vault server fills the per-ruleset sheet skeleton (the ruleset's attributes, skills, defense scaffolding, and the rest) for any sections the caller omits — a minimal { name, ruleset } body produces the same shape the web and iOS clients create. The passthrough schema accepts richer structure when you want to set sections inline at create time. Set type: "monster" (lowercase) to mark a monster. The new character is owned by the calling user. Note: characters can be linked to active play campaigns; modify them with care if so.
Inputs: name (required), ruleset (required), core, dead, +20 more. Returns: _id
vault_create_itemCreate a vault itemBInspect
Create a new user-authored item of any of the ruleset's item types. Vault validates ruleset-specific fields (damage, properties, equip slots, weight); send them via the passthrough schema. The new item is owned by the calling user.
Inputs: name (required), type (required), ogl, cost, +49 more. Returns: _id
vault_create_ruleCreate a vault ruleAInspect
Create a new user-authored rule of any rule type (the type field lists them). The new rule is owned by the calling user and is a 'house rule' unless the caller is an admin with Admin Mode on. Vault validates the payload; missing required fields return a vault error.
Inputs: name (required), age, ogl, feat, +68 more. Returns: _id
vault_create_spellCreate a vault spellBInspect
Create a new user-authored spell or power. Vault validates ruleset-specific required fields (level, casting time, components, range, duration, etc.); send them via the passthrough schema. The new spell is owned by the calling user.
Inputs: name (required), ogl, area, rank, +47 more. Returns: _id
vault_delete_characterDelete a vault characterADestructiveIdempotentInspect
Permanently delete a character by id. Caution: a deleted character is removed from any campaigns or expeditions referencing it. Run vault_get_character first to inspect linkage.
Inputs: id (required). Returns: id, deleted
vault_delete_itemDelete a vault itemBDestructiveIdempotentInspect
Permanently delete a user-authored item by id. Cannot delete stock content.
Inputs: id (required). Returns: id, deleted
vault_delete_ruleDelete a vault ruleADestructiveIdempotentInspect
Permanently delete a user-authored rule by id. Cannot delete stock content. Pair with vault_get_rule first to confirm the target.
Inputs: id (required). Returns: id, deleted
vault_delete_spellDelete a vault spellADestructiveIdempotentInspect
Permanently delete a user-authored spell by id. Cannot delete stock content.
Inputs: id (required). Returns: id, deleted
vault_detach_companionDetach a companion from a characterADestructiveIdempotentInspect
Remove a companion row from a Main character's sheet by the ROW's _id (from the companions[] array — not the buddy's own character id). Detaching an 'owned' row leaves the referenced character in the user's vault untouched; detaching a 'link' row discards the locally-tracked overlay counters (the source character is untouched either way). Response is { companions, updatedAt }; ADOPT the returned updatedAt as the Main character's fresh stamp.
Inputs: id (required), companionId (required). Returns: object
vault_get_authoring_guideGet a vault authoring guideARead-onlyIdempotentInspect
Fetch a markdown reference guide that teaches the conventions for authoring a specific entity type in a specific ruleset. Returns the full markdown body, including front-matter metadata (ruleset, entityType, version) at the top. Entity types: 'monster' — monster stat-block authoring (the field map, the stat block math, action types, spell formatting, resistances/immunities, keywords, a worked example), authored via vault_build_monster or vault_create_character + vault_update_character; 'rule' — classes / species / backgrounds / feats / abilities (the type taxonomy, the parent→Ability grant model, type-specific section fields, and the shared mechanics blocks: proficiencyChoices, spellChoices, spellListChoices, preparedSpells, freeCast, uses, ruleChoice, statBonuses), authored via vault_create_rule + vault_update_rule; 'spell' — the spell detail header (casting time / range / area / components / duration), the categories (Class(es)) membership convention, the damage/healing/effect mechanics blocks with upcasting (spellSlot scaling and slotIncrement), recurringDamage with its scaling and save, and extraDamage (a second damage packet), authored via vault_create_spell + vault_update_spell. Pass the ruleset code you are authoring for (list_rulesets gives the codes). Call this BEFORE authoring the matching entity so the result follows the established conventions instead of inferring shape from one-off samples. Returns a 'not found' tool error when the requested entityType / rulesetCode combination does not have a published guide yet.
Inputs: entityType (required), rulesetCode. Returns: object
vault_get_characterGet a vault characterARead-onlyIdempotentInspect
Fetch one character document by id. Defaults to a summary shape: combat-relevant top-level fields (attributes, defense, offense, AC, HP, actions, skills) preserved; bulk text bodies on populated rule/item/spell refs and inline snapshots trimmed; notes reduced to names; trackables reduced to name, counts, type, and the fields that link and refill them (_rule, _spell, _item, slotLevel, recovery), so the list can be sent back whole. Pass detail: 'full' for the populated shape with every description inline. The companions[] array (buddy ties — see vault_attach_companion) rides along untrimmed in both shapes, overlay state included; each row's _ref is a bare character id you can fetch with this tool. linkGroup, when present, is the id shared by this persona's linked sheets in other rulesets (created via vault_spawn_linked_character); it rides reads only and is not writable through the update tool.
Inputs: id (required), detail. Returns: _id
vault_get_itemGet a vault itemARead-onlyIdempotentInspect
Fetch one item document by id, including damage info, weight, properties, equip slots, and ammo settings. Pair with vault_search_items to locate the id first.
Inputs: id (required). Returns: _id
vault_get_levelup_optionsRead a character's level-up planARead-onlyIdempotentInspect
Read the level-up plan for a character whose ruleset has guided level-up (vault answers an error naming the ruleset otherwise) — the same computation vault's web wizard renders. Without classRuleId: the CHOOSER (the character's class entries with stored levels, the multiclass candidates each with warn-only prerequisite warnings[], xp.minimumForNext, atMaxLevel). A character with NO class entries (a hand-made sheet) gets RECORD mode instead: needsClassRecord: true plus recordOptions[] (every usable base class with subclasses[] and its subclassLevel) — record the existing classes with vault_record_pc_classes first, then re-read; the target plan and vault_level_up_pc reject a class-less character. With classRuleId: the TARGET PLAN for advancing that class one level — features[] (gained at the new level) / subclassFeatures[] / growth[] (held rules whose choice counts grew; their counts are DELTAS, "pick N more") each carrying its open choice blocks in the creation-option shape, plus multiclassGrants (entering a new class: fixed proficiency lines + skill/tool pickers), hitPoints {hitDie, average, conModifier}, prerequisiteWarnings[] (multiclass entry is warn-only, the player may proceed), spellSlots (combined multiclass pool preview, null when the plan has no combined pool), and xp {current, minimumForNewTotal}. Add subclassRuleId (at a subclass level, before committing the pick) to preview that candidate's features. ruleChoice pools arrive prerequisite-FILTERED — every listed option is one the character qualifies for at the level being gained. Read this before vault_level_up_pc and key every pick off what it returns.
Inputs: characterId (required), classRuleId, subclassRuleId. Returns: object
vault_get_pc_creation_optionsRead character-creation optionsARead-onlyIdempotentInspect
Read the legal choices for guided character creation — the same projections vault's web wizard reads. Pass ruleset (one with guided creation: the ruleset field's list; list_rulesets gives each code's label) and kind to select one list: 'class' / 'species' / 'background' / 'feat' return the option projections (the calling user's own content plus stock, each option carrying its nested choices: skillChoices, toolChoices, startingEquipmentOptions, and per applied ability/feat — proficiencyChoices, spellChoices, spellListChoices, preparedSpells, and choice whose options carry a type; an option in a choice, and a species' lineage option, may carry abilities with their own nested choices, and a Feat option carries its prerequisites and its own choice, picked in the choice map of the selection that owns it (abilityChoices for the class, speciesAbilityChoices for the species, backgroundFeatChoices for a background's feat, backgroundAbilityChoices for a background's own abilities) keyed by that rule's _id; a background option also carries skillChoices + languages, a species option carries languages; background bump modes / feat, etc.); 'feat' returns every feat (a feat picked via an ability's choice carries its own proficiency/spell sub-choices); 'constants' returns the static reference data (skill list with attributes, ability-score methods with each method's data, language options + pick count, alignments, background bump modes, max ability score, and originFeatCategory — the feat category the background's open feat slot is restricted to; filter the 'feat' list to it for the background pick). Use this BEFORE vault_build_pc so every id and pick you send is one the user is actually entitled to. Start with 'constants' and 'class', then read 'species' / 'background' / 'feat' as the build takes shape. Campaigns and Worlds: with no campaignIds or worldIds the options are stock plus the user's own content. Ask the user which campaigns and Worlds the character will join (find campaign ids with play_list_joinable_campaigns for this ruleset, World ids with imagine_list_my_worlds / imagine_search_public_worlds) and pass them on every option read and to vault_build_pc: each chosen campaign and World adds its house content (an option that came from one carries sourceLabel, naming the Worlds or campaigns it came from), the stock every chosen World hides is left out, and the chosen Worlds' extra skills are counted as the character's skills when the options are worked out. Changing the choices can change what is offered, so read the lists again after a change. A chosen campaign or World that can no longer be joined fails the call with CREATION_CONTEXT_LOST, naming it and the reason.
Inputs: kind (required), ruleset, worldIds, campaignIds. Returns: object
vault_get_ruleGet a vault ruleARead-onlyIdempotentInspect
Fetch one rule document by id, including nested abilities, requirements, ability score bonuses, and starting equipment references. Pair with vault_search_rules to locate the id first.
Inputs: id (required). Returns: _id
vault_get_spellGet a vault spellARead-onlyIdempotentInspect
Fetch one spell document by id, including its level, casting time, range, components, duration, and full description. Pair with vault_search_spells to locate the id first.
Inputs: id (required). Returns: _id
vault_level_up_pcLevel up a player characterAInspect
Advance a character one level in a class, in one call, from a flat draft of choices, for a ruleset with guided level-up (vault answers an error naming the ruleset otherwise). A class-less character (no Class entries) is rejected — record its existing classes with vault_record_pc_classes first. Vault validates every pick against the plan's pools (prerequisites enforced; grown choices demand only their delta counts) and mutates the character: the class entry's stored level bumps (or a new class entry lands with the class's multiclassGrants), the level's features snapshot onto the sheet (a subclass picked through the class's subclass-choice ability lands as its own entry and cascades its features), ability-score increases bake, HP and hit dice grow per the hitPoints choice, use-counters resize (spent uses stay spent), the combined multiclass spell-slot pool reconciles, core.class updates to " , ...", XP floors at the new level's minimum (or your exact xp), and a level-up note records the choices; the engine applies every rule behind those changes. Read vault_get_levelup_options first — required: characterId, classRuleId, hitPoints. Supply abilityChoices for every feature choice the plan surfaced (including the subclass pick and grown choice lists), the sub-pick maps for anything the picked options themselves carry (a Feat picked at an Ability Score Improvement level may carry its own choice and abilities, whose picks go in the same maps), spellSwapPicks for the optional known-spell swaps the plan offers, multiclassSkillProficiencies/multiclassToolProficiencies when entering a class, and optional exact xp. The updated character and a summary of what changed are returned. On an invalid draft vault returns the specific reason as a tool error — fix the draft and retry; if a surfaced pick genuinely cannot be satisfied, allowIncomplete: true applies the level and skips the shortfall instead.
Inputs: hitPoints (required), characterId (required), classRuleId (required), xp, +11 more. Returns: object
vault_list_character_worldsList a character's WorldsARead-onlyIdempotentInspect
List the imagine Worlds a character is in, in the order it joined them: [{ _id, name, link }] (link is null for a World with no link name). A character can be in many Worlds; while its owner can view a World, the character is offered what the World adds, not offered the stock the World hides, gets its extra skills, and is offered its extra damage types of its ruleset. Every World the character is in is listed, including one its owner can no longer view. Add or remove a World with imagine_add_character_to_world / imagine_remove_character_from_world. Readable by whoever may view the character's sheet; 404 for an unknown character or one the user may not view.
Inputs: id (required). Returns: object
vault_list_convertible_charactersList the user's characters that can be converted into a rulesetARead-onlyIdempotentInspect
List the calling user's own characters that vault offers a conversion for into the given ruleset (pass a ruleset code from list_rulesets). Use it when the user wants a version of an existing character in a newer ruleset and has not said which character, or to find out whether any conversion is on offer. Vault decides everything here: which rulesets convert into the one asked for, and which characters are offered (the user's own player characters, not monsters, that have no linked sheet in that ruleset yet, or one that is still blank). Returns { ruleset: { from, to }, characters: [{ _id, name, image, ruleset, core, updatedAt, fills }] }, by name: ruleset carries the two ruleset codes, and fills is true when converting that character fills in a blank linked sheet it already has, so it takes no character slot. A ruleset nothing converts into, or one the user is not entitled to, answers { ruleset: null, characters: [] }: say that no conversion is offered. Then call vault_preview_character_conversion with the chosen character's _id. Only the caller's own characters are ever listed; for another user's character an admin goes straight to the preview.
Inputs: ruleset (required). Returns: object
vault_list_linked_charactersList a character's linked sheetsARead-onlyIdempotentInspect
List the linked sibling sheets of a character the user may edit (their own, or any for an admin with Admin Mode on) — every OTHER sheet in its linkGroup (the same persona in other rulesets, created via vault_spawn_linked_character). Returns summary rows (_id, name, ruleset, image, dead, active, linkGroup); follow with vault_get_character on a returned id for a full sheet. A character with no linkGroup returns an empty list. 404 for an unknown character or one the user may not edit.
Inputs: id (required). Returns: object
vault_preview_character_conversionPreview converting a character to its ruleset's successorARead-onlyIdempotentInspect
Preview the version vault would make, in the ruleset that succeeds its own, of a character the user may edit (their own, or any for an admin with Admin Mode on). Creates nothing. Vault decides which rulesets convert and to which: the result's ruleset is { from, to } (codes; list_rulesets has their labels), and a character of a ruleset with no successor answers 409. The conversion makes a new version of the same character as its linked sheet in ruleset.to, beside the untouched original: it translates the sheet's records and keeps its numbers (ability scores, hit points, skills), and it is not a rules rebuild. The conversion asks the user nothing: vault makes every choice and reports it, and anything the user disagrees with they change on the new sheet afterward. Returns character ({ _id, name, updatedAt }), ruleset, fills (the blank linked sheet that will be filled in, or null when a new character will be made), and report, the forecast of what the conversion will do: { sections: [{ key, title, count, rows }] }, each row { name, result, note, text } (the thing on the original, what it becomes, and a sentence about it), or { name, before, after, text } for a total that comes out different. Every row's text is what follows its name, as vault words it ( → <result>, : <before>, now <after>, or empty): show each row as its name, then its text, then its note. Show the user the report as vault gives it, section by section, and ask whether to convert; then call vault_convert_character with character.updatedAt. Vault answers 409 when the character's ruleset does not convert, the character is not a player character, it already has a linked sheet in ruleset.to that has been used (deleting that sheet makes way), or the character was saved while vault read it (OUT_OF_SYNC: preview again), 403 when the owner is at the character limit or lacks the ruleset, and 404 for an unknown character or one the user may not edit. A 500 here is a fault in vault's own content that this character's conversion ran into; trying again will not fix it, so tell the user it needs reporting.
Inputs: id (required). Returns: object
vault_record_pc_classesRecord a class-less character's existing classesAInspect
The class-less on-ramp to the level-up flow. A hand-made character with no Class entries on its sheet can't level up (vault rejects the plan and the apply) — this tool records the class(es) and level(s) the character is ALREADY playing so the wizard can take over at the next level. It stamps identity snapshots ONLY: no features, proficiencies, HP, or trackables are granted — the sheet is trusted to already carry everything. Call vault_get_levelup_options first: RECORD mode (needsClassRecord: true) ships recordOptions[] (base classes with subclasses[] and subclassLevel) and totalLevel, the character's XP-derived level. The recorded levels must sum to EXACTLY that totalLevel (XP is the authority; vault never rewrites it) and a row may carry a subclass only at/above the option's subclassLevel. Rejected once any class entry exists. On success vault sets each class snapshot's stored level, attaches subclasses, updates core.class, appends a note, and returns { character, summary } — then call vault_get_levelup_options again for the normal chooser.
Inputs: classes (required), characterId (required). Returns: object
vault_search_charactersSearch vault charactersARead-onlyIdempotentInspect
Search PCs and NPCs (any character whose type is NOT the lowercase monster marker) the user owns, plus stock template characters. Use this to locate a player character or NPC the user has authored. Authored monsters are hidden — for creature stat blocks use the dedicated vault_search_monsters tool instead. Defaults to a compact summary shape (identification + image + class/race/background + linkGroup — the id tying a persona's per-ruleset linked sheets together; sheets sharing a linkGroup are the same persona in different rulesets); pass detail: 'full' to receive each character's full sheet (attributes, skills, rules, items, spells) inline.
Inputs: name, skip, sort, type, +3 more. Returns: results, pagination
vault_search_itemsSearch vault itemsARead-onlyIdempotentInspect
Search the item library the user has access to (stock items plus their own house items). Use this to locate an item by name, type (the catalog's own item types), or ruleset. Defaults to a compact summary shape (identification + summary + weight + cost + publisher / source); pass detail: 'full' to receive each item's full description and properties array inline.
Inputs: name, skip, sort, type, +5 more. Returns: results, pagination
vault_search_monstersSearch vault monstersARead-onlyIdempotentInspect
Search authored monsters (characters with the lowercase type: monster marker) the user owns, plus any stock template monsters. This is the right tool for creature stat-block lookups; vault_search_characters deliberately hides monsters by default and this sibling exists so the LLM doesn't have to remember the filter trick. The type filter is baked into the call. Defaults to a compact summary shape; pass detail: 'full' to receive each monster's full stat block (attributes, defense, offense, AC, HP, actions, skills) inline. Pair with vault_get_character on a returned id for the full document.
Inputs: name, skip, sort, limit, +2 more. Returns: results, pagination
vault_search_rulesSearch vault rulesARead-onlyIdempotentInspect
Search the rules library the user has access to (stock content plus their own house rules). Use this to locate a rule by name, type (the type field lists the rule types), or ruleset. Defaults to a compact summary shape (identification + summary + categories + publisher / source); pass detail: 'full' to receive each rule's full description and embedded sub-document arrays inline.
Inputs: name, skip, sort, type, +5 more. Returns: results, pagination
vault_search_spellsSearch vault spellsARead-onlyIdempotentInspect
Search the spell library the user has access to (stock spells plus their own house spells). Use this to locate a spell or power by name, ruleset, or type, or to list one class's spell list (spellList plus ruleset). Defaults to a compact summary shape (identification + summary + level + school + classes + categories + publisher / source); pass detail: 'full' to receive each spell's full description inline.
Inputs: name, skip, sort, type, +6 more. Returns: results, pagination
vault_spawn_linked_characterSpawn a linked character sheet in another rulesetAInspect
Create a linked sibling sheet for a character the user may edit (their own, or any for an admin with Admin Mode on), in a different ruleset; the new sheet belongs to the source's owner — the same persona with sheets in multiple rulesets, tied together by a shared linkGroup id. The server builds the new sheet from the target ruleset's template and copies only the descriptive/identity fields in the sync manifest (name, description, image, appearance, personality, and similar); mechanical and build data (class, level, attributes, skills, rules/items/spells, notes) stays ruleset-local and starts fresh. After the spawn, edits to a manifest field on any linked sheet cascade to its siblings automatically. Play campaign assignments of the source are replicated onto campaign legs matching the new ruleset where they exist. One sheet per ruleset per group: vault answers 409 when the source is already that ruleset or a linked sibling already occupies it, 403 when the source's owner lacks the grant for a restricted ruleset, and 404 for an unknown source or one the user may not edit. This is NOT vault_clone_character — clone deep-copies the whole ruleset-specific sheet; spawn deliberately does not. Before spawning, check vault_list_convertible_characters for the target ruleset: when it lists this character, vault converts it into that ruleset (vault_preview_character_conversion, then vault_convert_character), carrying its classes, features, spells, and items over, so offer the conversion and spawn a blank sheet only when the user wants one. When the list does not name this character for that ruleset (it answers { ruleset: null, characters: [] }, or leaves the character out), spawn as described above.
Inputs: id (required), ruleset. Returns: object
vault_unlink_characterUnlink a character from its linked-sheet groupADestructiveIdempotentInspect
Remove one character from its linked-sheet group by clearing its linkGroup. The sheet keeps every field it has — nothing is deleted — but it stops cascading descriptive-field edits to its former siblings and stops receiving theirs. The remaining siblings keep the group (a group of one is inert). There is no re-join: a later vault_spawn_linked_character from this sheet mints a NEW group. Vault answers 404 when the character is unknown, one the user may not edit, or has no linkGroup to clear (so a repeated unlink reads as 404, not an error state). Returns { unlinked: true }.
Inputs: id (required). Returns: object
vault_update_characterUpdate a vault characterAIdempotentInspect
Patch fields on an existing character by id. Only supplied fields change, with one distinction: object sub-docs (defense, core, offense, speed, personality, settings) deep-merge — nested keys you omit are preserved — but ARRAY fields (items, spells, rules, skills, actions, trackables, attributes, notes) are atomic: the array you send replaces the stored array wholesale. To add or edit one array entry, vault_get_character first, modify the returned array, and send the complete array back, each items row with the _id it came with (a row's usage counters in trackables are linked to that id; a row left out of items takes its counters with it). Sending null for a field is treated the same as omitting it (the field keeps its current value) — null does NOT clear; to clear a text field send an empty string. This is also the canonical tool for editing a play campaign character's HP, conditions, or inventory; play characters are pointers to vault characters and play has no direct character-write endpoint. AC caution: when the character's settings.autoPassiveBonuses is true (the default for new characters in rulesets with sheet automation), the armor and shield rows of defense.armorClass are derived from equipped items and recomputed on every sheet load — change AC by setting equipped on the character's armor/shield items, not by writing those rows; when the toggle is false, defense.armorClass is manually authored and writing it directly is correct. settings.privateSheet: true hides the character's sheet from signed-out visitors on the web (its page stays public); turning it on takes a membership (member, premium, vip, or admin) and is refused otherwise, while turning it off is always allowed. Caution: mutations may affect any active play campaign or expedition referencing this character. Consider running vault_get_character first to inspect linkage. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_character read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written — writing from memory of an earlier read is not possible. companions is NOT writable here (it is stripped): manage buddy ties with vault_attach_companion / vault_detach_companion, and a linked buddy's tracked values with vault_update_companion_state. linkGroup is NOT writable here either (also stripped): linked-sheet group membership is created by vault_spawn_linked_character and only vault's unlink endpoint clears it.
Inputs: id (required), baseUpdatedAt (required), core, dead, +22 more. Returns: _id
vault_update_companion_stateUpdate a linked companion's tracked valuesAIdempotentInspect
Write a LINK-mode companion row's transient overlay — the locally-tracked hit points, temp HP, hit dice, death saves, exhaustion, stress marks, and trackable/free-cast counters for a buddy the user doesn't own. The source character is never written. The state you send replaces the row's stored overlay wholesale: vault_get_character the Main first, modify that row's state, send it back complete. Maximums never belong in the overlay (they derive from the source; vault drops them). Rows in 'owned' (or legacy 'clone') mode have no overlay — edit the referenced character directly with vault_update_character instead. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_character read of the MAIN character; a stale value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), state (required), companionId (required), baseUpdatedAt (required). Returns: object
vault_update_itemUpdate a vault itemAIdempotentInspect
Patch fields on an existing user-authored item by id. Only supplied fields change. Use vault_search_items / vault_get_item to confirm the id first. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_item read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), ogl, cost, +51 more. Returns: _id
vault_update_ruleUpdate a vault ruleAIdempotentInspect
Patch fields on an existing user-authored rule by id. Only the fields you supply are changed; everything else is preserved, with one distinction: ARRAY fields (abilities, spellAbilities, spellChoices, uses, and the other lists) are atomic, so the array you send replaces the stored array wholesale. To add or edit one entry, vault_get_rule first, modify the returned array, and send the complete array back. Use vault_search_rules / vault_get_rule first to confirm the id and current state. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_rule read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), age, ogl, +70 more. Returns: _id
vault_update_spellUpdate a vault spellAIdempotentInspect
Patch fields on an existing user-authored spell by id. Only supplied fields change. Use vault_search_spells / vault_get_spell to confirm the id first. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_spell read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.
Inputs: id (required), baseUpdatedAt (required), ogl, area, +49 more. Returns: _id
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Your tabletop campaign's journal, wiki, map, character sheets and combat tracker.
Tabletop RPG campaign wiki for game masters: NPCs, places, sessions, encounters, notes, roll tables
Roll RPG NPCs (Foundry VTT & SillyTavern V2), import stylized art, MP3 barks & talking MP4s.
D&D and TTRPG campaign manager for GMs: your AI reads and writes a live, typed campaign database.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceConnects AI assistants to TTRPG campaign data for managing characters, sessions, locations, factions, items, quests, and more.4MIT
- AlicenseAqualityBmaintenanceHolonovel turns a tabletop RPG rulebook and an AI client into a running game. The server enforces every rule and remembers your campaign as structured state the AI can't forget; the AI just narrates. D&D 5e, Starfinder, or any rulebook.371MIT
- AlicenseNot gradedqualityBmaintenanceConnect to your TTRPG campaign's repository and database. Instead of retrieving prose, its 48 tools (20 read, 28 write) return typed state: 14 entity schemas (NPCs, factions, locations, sessions, lore), relationship and knowledge-graph queries, wiki blocks, and a narrative-state bundle of open threads and canon facts.2MIT

archivistofficial
AlicenseNot gradedqualityDmaintenanceProvides read-only SRD lookup and deterministic enrichment tools for D&D 5e content generation, including search, entity retrieval, and generation of monsters, spells, items, NPCs, and encounters.MIT
Glama MCP Gateway
Add one secure layer between your agents and this server.