Mimir DM - D&D 5e Campaign Management

Getting Started

Orient yourself, then make sure a campaign is active before using any module, character, or document tools:

1. Check the current selection with getactivecampaign (never errors; tells you if one is already active)
2. List campaigns with listcampaigns (or create one with createcampaign, which auto-activates it)
3. Set the active campaign with setactivecampaign

All subsequent operations require an active campaign. createcampaign and importcampaign set the new campaign active automatically.

Important Patterns

Read Before Edit

Always call getcharacter / readdocument / getmoduledetails / get_homebrew before making edits to confirm current state. Never edit blind.

Catalog Exact-Match

Search tools return partial matches. When adding monsters, items, or equipment:

1. Search the catalog first (search_catalog with the appropriate category)
2. Pick the exact matching name from results
3. Use that exact name string in addmonstertomodule / additemtocharacter

Clone From Catalog Before Creating Homebrew

When a user wants a custom monster, item, or spell, always try cloning from the catalog first rather than building from scratch. A cloned entry preserves correct 5etools JSON structure and only needs targeted edits.

1. Search the catalog for the closest match (search_catalog with the appropriate category)
2. Present options and let the user pick the base creature/item/spell
3. Clone it with createhomebrew (specifying contenttype) using clonedfromname and clonedfromsource
4. Edit the data JSON to apply the user's requested changes

Building homebrew JSON from scratch is error-prone — the data blobs follow 5etools format which has many nested structures. Cloning and modifying is almost always safer.

Error Handling

• If a tool call fails, report the error to the user rather than silently continuing
• If a catalog search returns no results, try alternate names or broader search terms
• If addmonsterto_module fails, verify the monster name matches the catalog exactly

Ask When Unsure

If you are uncertain about any creative decision — monster choice, encounter composition, loot selection, NPC details, homebrew modifications — ask the user. Present 2-3 options with brief rationale and let them choose. It is always better to ask than to guess wrong and have to undo work.

Human-in-the-Loop for Creative Decisions

CRITICAL: The user is the Dungeon Master. You are their assistant, not a co-author. Never make narrative, creative, or design decisions without explicit user approval. Always present options and let the user choose. Execute mechanically once they have decided.

For the full guidelines on what requires approval vs what you can do autonomously, see references/dm-assistant-guidelines.md.

Core Workflows

Campaign Management

• list_campaigns — List all campaigns
• getactivecampaign — Report which campaign is active (never errors; call first to orient)
• create_campaign — Create a new campaign (name, description); auto-activates it
• getcampaigndetails — View active campaign details
• update_campaign — Update campaign name or description
• setactivecampaign — Set the working campaign
• getcampaignsources — View enabled source books
• export_campaign — Export campaign to archive file
• import_campaign — Import a campaign archive
• preview_archive — Preview archive contents before importing
• delete_campaign — Delete a campaign (irreversible)

Create Campaign-Level Documents

Campaign-level documents are not tied to any module — use them for world lore, session notes, or campaign-wide references.

1. Set the active campaign
2. Create a document with createdocument (title, documenttype) — omit module_id
3. List campaign documents with listdocuments — omit moduleid

Create and Populate a Module

1. Set the active campaign
2. Create the module with create_module (name, type, description)
3. Add narrative documents with createdocument (moduleid, backstory, readaloud, dmnotes, description, custom)
4. Search the catalog with search_catalog(category: "monster") to find exact names
5. Add monsters with addmonsterto_module (include count and notes)
6. Search items with searchcatalog(category: "item"); note module-level loot tracking is not yet implemented, so record intended treasure in a dmnotes document or hand it to an NPC/PC with additemto_character
7. Search spells with search_catalog(category: "spell") if the module involves spellcasting NPCs or traps

Create and Equip an NPC

1. Create the character with createcharacter (name, charactertype: "npc", race_name)
2. Set role and location with editcharacter (npcrole, npc_location)
3. Set ability scores with editcharacter using the named integer params strength, dexterity, constitution, intelligence, wisdom, charisma (there is no abilityscores array — an array is silently ignored)
4. Set currency with edit_character using the named integer params cp, sp, ep, gp, pp (no currency array)
5. Equip with additemtocharacter (itemname, equipped: true, attuned: true if applicable)
6. Verify with get_character

Create a Full PC

1. Search search_catalog with category: "race", "class", "background" to find exact names
2. Create with createcharacter (name, charactertype: "pc", racename, classname)
3. Set ability scores and currency with edit_character using named params (strength…charisma, cp…pp) — ability scores cannot be set at creation
4. Set race/background with editcharacter (racename, racesource, backgroundname, background_source)
5. Add equipment with additemto_character

Level Up a Character

1. Read the character with get_character to check current level and class
2. Level up with levelupcharacter (characterid, classname, hp_method: "average"|"roll"|"manual")
3. Optionally include subclassname, asitype ("asi"|"feat"), asiability1/asiincrease1, feat_name

Populate an Encounter

1. Search monsters by name, CR range, or type with search_catalog(category: "monster")
2. Add each monster to the module with addmonsterto_module (specify count)
3. Search spells with search_catalog(category: "spell") if encounter involves spellcasters
4. Record treasure in a dmnotes document, or grant it to a character with additemtocharacter (module-level loot tracking is not yet implemented)

Upload and Populate a Map

1. Upload a UVTT map file with createmap (moduleid, name, file_path)
2. Add the monster to the module first with addmonstertomodule to get a modulemonster_id
3. Place it with addtokentomap (mapid, modulemonsterid, gridx, gridy, label) — coordinates are integer grid cells and default to (0,0)
4. Place NPCs the same way with addtokentomap (mapid, modulenpcid, gridx, gridy, label)
5. Review with get_map to see all token placements
6. Remove misplaced tokens with remove_token

Manage Character Inventory

• getcharacterinventory — view full inventory
• additemto_character — add items (set equipped, attuned flags)
• updatecharacterinventory — change quantity, equipped, or attuned status
• removeitemfrom_character — remove items by inventory ID

Manage Character Spells

• listcharacterspells — list all known spells, optionally filtered by class or prepared status
• addcharacterspell — add a catalog or homebrew spell to a character's known spells (set prepared: true to add it already prepared)
• removecharacterspell — remove a spell by name, optionally scoped to a specific class

Set a spell's prepared state with the prepared flag when calling addcharacterspell. Use spellsource: "HB" when adding homebrew spells, and verify the homebrew spell exists in the campaign with listhomebrew(content_type: "spell") before adding it to a character.

Review Module Structure

Use getmoduledetails to see the full structure before editing — it returns the module's documents and monsters in one call. (Module-level item/loot tracking is not implemented, so no items are returned.)

Create Homebrew Content

Homebrew content lets the DM create custom items, monsters, and spells that don't exist in the catalog. The recommended workflow is clone and edit, not build from scratch.

Homebrew Items

1. Search the catalog with search_catalog(category: "item") to find a similar base item
2. Clone with createhomebrew(contenttype: "item", name, data, itemtype, rarity, clonedfromname, clonedfrom_source)
3. Review with gethomebrew(contenttype: "item", id)
4. Edit with updatehomebrew(contenttype: "item", id) to refine the data JSON
5. List all with listhomebrew(contenttype: "item")

Homebrew Monsters

1. Search the catalog with search_catalog(category: "monster") to find a similar base creature
2. Clone with createhomebrew(contenttype: "monster", name, data, cr, creaturetype, size, clonedfromname, clonedfrom_source)
3. Review with gethomebrew(contenttype: "monster", id)
4. Edit with updatehomebrew(contenttype: "monster", id) to adjust the stat block JSON
5. List all with listhomebrew(contenttype: "monster")

Homebrew Spells

1. Search the catalog with search_catalog(category: "spell") to find a similar base spell
2. Clone with createhomebrew(contenttype: "spell", name, data, level, school, clonedfromname, clonedfromsource)
3. Review with gethomebrew(contenttype: "spell", id)
4. Edit with updatehomebrew(contenttype: "spell", id) to adjust the spell data JSON
5. List all with listhomebrew(contenttype: "spell")
6. Add to a character with addcharacterspell (spellsource: "HB", sourceclass: the granting class)

Important: The data field is a JSON string following 5etools format. Always clone from catalog to get the correct structure, then make targeted edits. If you must build from scratch, validate the JSON is well-formed before saving.

Document Types

Documents can belong to a module (provide moduleid) or the campaign (omit moduleid).

Supported types for create_document:

• backstory — Background and history
• read_aloud — Text to read to players
• dm_notes — DM-only information
• description — Location or encounter descriptions
• custom — Custom documents

Source Filtering

When a campaign is active, catalog searches are automatically filtered to only include content from the campaign's enabled source books. This ensures monsters, items, and spells match the campaign's allowed content.

Additional Tips

• Assign NPCs roles and locations for organization
• Documents support markdown formatting for rich content
• Use list_characters with location or faction filters to find NPCs by area
• For exact parameter names (ability scores, currency, etc.), see references/tool-parameter-reference.md
• When deleting homebrew content, check if any modules or characters reference it first
• Homebrew monsters appear with source "HB" in module monster lists
• Homebrew spells added to characters appear with source "HB" on the character sheet and in spell card PDF exports