Without journalId: every journal with its pages (id, name, type). With journalId: the content of its first text page and the list of all its pages. With journalId and pageId: the content of that page; for image, video or PDF pages the content is the source address. Content comes in chunks of maxChars characters: when hasMore is true, call again with offset set to nextOffset, and never write a partial chunk back as the whole page.

Find journals by a text, ignoring case, in their names and in the HTML of their text pages. Each hit names the matching pages with a short excerpt, so the page can then be read with list-journals (journalId and pageId). The search runs inside Foundry, in one request.

Create a journal with exactly the given pages, in order, each stored as HTML exactly as sent (headings, images and @UUID links included). No template page is added. Only Gamemasters can see it. With folderName the journal goes into that journal folder (by id or exact name), which is created when it does not exist; without folderName it is created outside any folder. Returns the new journal id.

Replace the whole HTML content of a text page with the given HTML, stored as sent. Nothing is appended or wrapped. For content larger than one message, write the first chunk here and add the rest with journal-append-page, or use journal-page-from-file.

Add a new text page at the end of a journal, with the HTML stored as sent.

Append HTML to the end of a text page. Meant for content too large for one message: create the page with the first part, then append the rest in pieces of about 40000 characters. The pieces are joined as sent, so cut them between tags. Returns the new length.

Write an HTML file that is already in Foundry's data directory into a page. The browser fetches the file from the Foundry server itself and nothing of it crosses the bridge, so any size works. With pageId that text page is overwritten (an unknown pageId is an error); without it a new text page is added at the end.

Split a large text page into one page per section, cut at headings, inside Foundry so the content never crosses the bridge. The markup of each section is kept as it was. Content before the first heading becomes a page of its own. The new pages appear right behind the source page, which is kept unless deleteOriginal is true.

Give a journal a new name.

Delete one page of a journal for good. Needs the journal permission level "create, change and delete", which is off by default.

Delete a whole journal with all its pages for good. Needs the journal permission level "create, change and delete", which is off by default.

Replace external image addresses in text pages with local paths, for imported adventures that load their images from a CDN. Every img whose src starts with urlPattern (ignoring case) gets localPrefix followed by the file name of the old address. Runs inside Foundry. Use dryRun first.

Turn leftover 5etools tags, @creature[Name|Source] and @item[Name|Source] with an optional third part as label, into Foundry links to compendium entries. Creatures are looked up in actorPacks, items in itemPacks, in the given order, by name ignoring case; for creatures the id of the official 2024 books is tried as well, so an English tag also finds a translated compendium. Every tag that could not be resolved is listed. Use dryRun first.

After moving files on disk, replace their old path prefix in every document of the world in one step: scenes with tokens, tiles, drawings, notes, sounds, walls, lights and regions; actors with items and effects; items; journals with pages (image pages and images in text); playlists; roll tables; cards; macros. A prefix only matches where a path begins and up to a path boundary, so "Bilder/Token" never touches "Bilder/Tokenringe", and percent-encoded spellings are found too. Runs inside Foundry. Checks the permission of every kind it would change before writing anything. Always run dryRun first and read the report.

Set an actor's prototype token image, and optionally its portrait, its token name and the dynamic token ring. With ring true the token image also becomes the subject inside the ring, and without ringColor the ring is coloured by disposition: hostile red, neutral blue, friendly green. The actor is found by id or exact name.

Items on an actor are copies. When their compendium was translated or corrected later, the copies keep the old text. This pulls name, image and description again from each item's source, and never touches mechanics: levels, uses, prepared spells, quantity, equipment and attunement stay. Items without a resolvable source are listed and left alone. Always run dryRun first.

Rename a sidebar folder, found by its id or exact name, optionally only among folders of one document type. When several folders have that name, the error lists them so the id can be passed instead. Contents stay.

Delete a sidebar folder, found by its id or exact name. By default its documents and subfolders move up one level. With deleteContents true, all documents and subfolders inside are deleted as well. Needs the folder permission level "create, change and delete", and for deleteContents the same level for the documents inside.

Read the basics of the Foundry world that is open right now: its id and title, the game system and its version, the Foundry version, how many users exist, and who is logged in. Use it first to learn which world and system you are working with.

List the scenes of the world with id, name, whether active, size, grid size, background and how many walls, tokens, lights and sounds each holds. filter narrows by a part of the name, in any case.

List every scene folder with its full path, its id and how many scenes lie directly in it. Call it before create-scene or update-scene to pick a valid folderPath.

Describe the scene that is active for everyone: size, background, navigation, how many walls, lights, sounds and notes it holds, its notes, and with includeTokens its tokens. Hidden tokens are left out of the list and the summary unless includeHidden is set.

Create a scene from an image or video already in the Foundry data directory, such as a battlemap or a location picture. Without width and height the file is measured so the grid fits. templateName copies the settings of an existing scene (grid, lighting, level settings) but nothing that lies on its map and never its id. folderPath takes nested paths like "Locations/Harbour" and creates missing folders. journalIdentifier links a journal as the scene journal.

Recreate a scene from a JSON file in the Foundry data directory, for example one pulled out of a world backup, with its walls, tiles, lights, sounds, tokens and levels. The file travels as a file because a scene with walls is too large for the bridge. The scene always gets a new id unless keepId is set, is never active, and never overwrites an existing scene.

Change an existing scene: name, navigation label, background image or video, background colour, size, folder, navigation, or the linked scene journal. A new background without width and height is measured and the scene takes its size. An empty journalIdentifier removes the link. Every change is read back.

Place a note on a scene at pixel coordinates that opens a journal, or one page of it, when clicked. Useful to make the places on a town map clickable.

Create the thumbnail of a scene anew. Needed after a background swap: Foundry keeps showing the old picture in the sidebar until then.

Activate a scene for every player, by id or name. With optimize_view the view is centred on the map and zoomed so the whole map fits. Players see the switch at once, so this is a change to the world and needs writing to be allowed.

Delete a scene for good, by its id only, so a scene with a similar name is never hit. The active scene is never deleted; activate another one first. Needs the scene permission on "create, change and delete".

List every compendium with its type, entry count, lock state and whether the AI can write to it right now. "Editable" takes all layers into account: the write switch, the permission level for compendiums, the release list and the lock. An unlocked compendium can be written to no matter who ships it, unless the release list is filled. Call this before exporting to find the right pack id.

List all compendium packs with id, label, document type, game system and whether they are private, optionally filtered by document type. availableTypes names every type that occurs, also when a filter is set.

List what actually sits inside a compendium: ids, names, types and folders. list-compendiums only gives counts, so this is the way to check whether an archive holds what it should, to find duplicates, or to get the ids needed for later work. Reads the index only, never the full documents, and returns at most 1000 entries per call; when more follow, the answer says so with the next offset. Read only: it changes nothing and works at any permission level.

Search the names of compendium entries across all compendiums except scene compendiums. Every word of the query has to occur in the name; descriptions are not searched. Exact name matches come first. Creature filters need the adapter of the active game system: with packType "Actor" and the creature index they check real values, otherwise they are an estimate from names, and filters the system does not know are reported as ignored. For accurate filtering use list-creatures-by-criteria, and inspect single entries with get-compendium-item.

Retrieve one compendium entry in full: name, type, description, image, system data, contained items and effects and the whole document. compact returns key values, properties and at most five contained items instead, which is enough to decide between candidates.

Creature discovery for encounter building: a long list of creatures matching criteria, with little data per creature, so you can choose by name and fetch details with get-compendium-item only for the final selection. The filters are understood by the adapter of the active game system (D&D 5e: challenge rating, creature type, size, alignment, spells, legendary actions; Pathfinder 2e: level, traits, rarity; DSA5: experience level, species, culture, profession; WFRP4e: species, traits, prayers; Traveller: hits, psionics; Cosmere RPG: tier, role, defenses) and checked against the creature index. Filters the active system does not know are reported as ignored. Without an adapter for the system, filtering is refused and a call without filters lists every actor by name.

Create a new world compendium, for example to archive a finished chapter of a campaign. Choose the document type it will hold. Needs the compendium permission on "create and change".

Copy documents from the world into a compendium, to archive finished material. Select by name or id, or by the world folder they sit in; without either, everything of that type is copied. Ids are kept, so a document already in the compendium is overwritten instead of duplicated. A locked compendium is refused unless unlockIfNeeded is set; then the lock is lifted for this operation only and set again afterwards. The answer lists new, overwritten, skipped and, marked CAUTION, lost entries.

Copy a document out of a compendium into the world: playlists, scenes, journals, actors, roll tables, items, macros, cards. Always assigns a FRESH id, so it can never overwrite an existing world document. That is the difference to dragging an entry out by hand, which keeps the id and silently replaces whatever carries it. Names are matched as a whole; an ambiguous name is refused with the ids.

Sort entries of a compendium into a folder, creating the folder if needed. Entries are named exactly (ignoring case) or by id; names not found and ambiguous names are reported and left where they are. Same lock rules as export-to-compendium.

Lock or unlock a compendium. Which ones may be touched follows the module settings: by default every compendium, or only the ones on the release list if it has been filled in.

Remove named entries from a compendium, by id or by exact name. Only what is explicitly named is removed; there is deliberately no "empty this pack". Always run with dryRun first: it reports exactly what would go, what was not found and which names are ambiguous, without touching anything. Names are matched in their exact spelling, never as a part, and an ambiguous name is reported rather than guessed. If the selection covers every entry, confirmLabel is required as well. Needs the compendium permission on "create, change and delete".

Remove a world compendium and everything in it. This cannot be undone, so it is off by default: the compendium permission has to stand on "create, change and delete". The exact label must be passed as confirmLabel. Compendiums of a module or of the game system cannot be removed this way.

Show what the AI is currently allowed to do in this world: the switch "Allow Write Operations", the level per document kind (scenes, playlists, journals, roll tables, actors, folders, compendiums: read only, create and change, or additionally delete), the release list of compendiums and the modules released to offer tools of their own. Deleting is off by default everywhere. Call this when an action was refused, to see which setting has to change.

List the playlists in the world with their sounds. Use this to find the exact playlist and sound name before linking one to a scene, or to check whether a playlist referenced by a journal actually exists in the world.

Link a playlist, and optionally one specific sound, to a scene so it starts when the scene is activated. Pass an empty playlistName to remove the link. The playlist has to exist in the world; use import-from-compendium first if it only exists in a compendium. Names are matched exactly; a sound may also be given as part of its name, as long as only one sound matches.

Delete a playlist by its id. Refuses while the playlist is still linked to a scene, and names those scenes. Requires the playlist permission to be set to full.

List the roll tables in the world with their formula and number of results.

Create a roll table from a list of text results. Ranges are assigned consecutively when omitted (first entry 1, second 2, and so on) and the dice formula is derived from the highest range, so a six-entry table becomes 1d6 by itself. Overlapping ranges are refused; gaps, and numbers the formula can roll without an entry, are reported as warnings.

Delete a roll table by its id. Requires the roll table permission to be set to full.

Overview of one actor with few tokens: head values and the value block as the adapter of the game system reads them, every item with id, name and type (plus the fields the system marks as relevant, no descriptions), effects, actions and spellcasting where the system has them. Without an adapter for the game system only name, type and image are known, and notes says so. The actor is found by id, exact name or token id; similar names are suggested, never guessed. Fetch the full data of one item or effect with get-character-entity.

Full data of one item, action or effect of an actor: description, all system data (credentials removed, game data such as save or activity data kept) and its effects. Looks among items first (id or exact name), then actions, then effects; two entries of the same name are reported with their ids instead of picking one.

List the actors of the world with id, name, type, folder and whether they have an image, optionally of one type. When no actor has the given type, the answer names the types that exist.

Search inside one actor instead of loading all of it: items whose name or description contains the query, optionally of one item type or category, or actions and effects. Each match has id, name, type, a short plain description and the details the adapter of the game system adds (range, target, level, equipped and so on). Categories come from the adapter; without one there are none, and an unknown category is refused, never ignored.

Copy one actor entry of a compendium into the world, once per name, into the folder "Foundry MCP Creatures", and optionally place the copies as tokens in the active scene. Find packId and itemId with search-compendium first. At most 10 copies (and not more than the setting "maxActorsPerRequest"). The copy keeps a link to its entry, never its id; a remote token image is dropped so Foundry uses its default. Everything that could refuse, including the scene permission for addToScene, is checked before the first actor is created. The answer lists every actor with its real name, the placed tokens and every problem.

One compendium entry of any document type with everything needed before copying it into the world: name, type, compendium label, description, system data, every contained item with its system data, the effects, a short summary and the whole document. Credentials are removed. A missing compendium or entry is reported as such.

Create, change, delete and place world actors, and change or delete items on an actor. "create" makes actors with a type of the game system and free system data (the adapter of the system reshapes it where it knows how). "update" changes actors found by id or exact name and merges system data. "delete" removes actors by id for good and needs the actor permission "full". "place" puts world actors as tokens into the active scene. "update-items" and "delete-items" work on the items of one actor by item id; deleting needs "full". "describe" returns what the adapter of the game system says about actor data. Every target is checked before the first write, nothing found is named, and values the system did not store as written are listed as mismatches.

Items in the world and on actors. "create" makes world items (in a folder by id or path, created when missing and named in the answer), "list" filters world items by type, folder and part of the name, "update" changes world items by id, "add-to-actor" creates items directly on an actor, "remove-from-actor" deletes items of an actor by id or exact name (needs the actor permission "full"; a name that fits several items is refused), and "describe" returns the valid item types and the enumerated values the adapter of the game system reads from its configuration. Item types are checked against the game system before anything is written.

Start the use of an item of an actor (a spell, an ability, a consumable) in Foundry and return at once, without waiting for a dialog the Gamemaster may have to confirm. Targets are tokens of the active scene; if one cannot be found exactly, nothing is used. The adapter of the game system decides how the item is used and how consume and spellLevel apply; without one the usual item methods are tried, and failing those a plain chat message is posted. The answer says what was verified (targets, whether the use finished) and what was not (consumption).

Give players a permission level on actors, e.g. make John the owner of Aragorn, or give the party observer access to all friendly NPCs of the active scene. Actors and players are matched exactly (id or name, case does not matter), never by part of a name; Gamemasters are never changed. More than one actor or player needs confirmBulkOperation. Each pair is read back and reported, unchanged pairs included.

Remove the explicit permission a player has on an actor, so the default level of the actor applies again; the answer warns when that default still grants access. To hide an actor completely from a player, assign NONE with assign-actor-ownership instead. Needs confirmRemoval, and confirmBulkOperation when more than one actor or player is affected.

Show which level every player effectively has on actors, and whether it is set for that player or comes from the default level of the actor. One actor or all, one player or all; Gamemasters are left out because they own everything.

[D&D 5e only] Create one NPC with a complete stat block and no items: type, size, alignment, challenge rating, ability scores, saving throw and skill proficiencies, hit points, armor class, speeds, senses, damage and condition traits, languages, biography and source. It goes into the folder "Foundry MCP Creatures". A name any actor already has (ignoring case) and a challenge rating the rules do not have are refused. Proficiency bonus and experience points are left to dnd5e, which derives them. Every value is read back; the answer lists warnings (e.g. a language that is not a dnd5e key) and anything stored differently. Add attacks, features and spells afterwards with dnd5e-add-feature.

[D&D 5e only] Add one thing to an existing dnd5e NPC or character; featureType chooses what, and each kind reads only its own parameters (the answer names the ignored ones).

• passive: a trait without a roll. Needs featureName.

• save: a feature forcing a saving throw with fixed DC, damage, optional template. Needs featureName, saveAbility, saveDC, damageParts; areaSize with areaType.

• attack: a weapon attack. Needs featureName, attackType, damageParts; rangeFt when ranged. The first damage part is the weapon damage.

• attack-with-save: an attack whose hit also forces a save with its own damage. Needs in addition saveAbility, saveDC, saveDamageParts.

• aura: area damage without attack or save; no lasting aura or effect is created. Needs featureName, damageParts, areaType, areaSize.

• spellcasting: casting ability and caster level of an NPC without class items, per class, level and rules version (2024 paladins and rangers have slots at level 1). dnd5e derives the slots; actors with class items are refused. Needs spellcastingClass, spellcastingLevel.

• spells: copy spells by English name from compendiums. Needs spellNames. An item name the actor already has (ignoring case) is refused. The actor is found by id, exact name or token id, never by part of a name. Everything written is read back. Run spellcasting before spells.

[D&D 5e only] Copy class and monster features by English name from item compendiums onto an actor, such as "Pack Tactics", "Multiattack" or "Action Surge". Names match whole and ignoring case; the first compendium in compendiumPacks with the name wins, and two entries of that name in one compendium are reported instead of guessed. Without compendiumPacks the standard compendiums of the world's rules version are searched (2024 class features are part of the class items and cannot be fetched one by one). Items the actor already has by name are skipped. Copies keep a link to their entry, never its id. The answer lists added, skipped, not found and failed names; for spells use dnd5e-add-feature with featureType "spells", for homebrew features featureType "passive" and the others.

Put a token at a new position on the active scene (or the scene in sceneIdentifier). x and y are scene pixels of the top left corner of the token; grid, walls and scene bounds are not checked. With animate the token glides there, otherwise it jumps. The answer gives the position Foundry stored.

Change properties of a token on the map (not of its actor): position, size in grid spaces, rotation, hidden, disposition (-2 secret, -1 hostile, 0 neutral, 1 friendly), displayed name, elevation, rotation lock. Other fields are refused with their names. Every change is read back; values Foundry stored differently come as warnings.

Remove tokens from the active scene (or the scene in sceneIdentifier), by their ids only. The actors stay in the actor directory; an unlinked token loses its own values with it. When one id is not on the scene, nothing is deleted and the answer says where that id lies. The answer lists every deleted and every failed token.

Read one token: position, size, appearance (rotation, scale, alpha, hidden, image), behaviour (disposition, elevation, rotation lock) and its actor with whether it is linked. Hidden tokens are read too. No actor values such as hit points; get-character reads those.

Set or remove a condition (such as prone, poisoned, blinded) on the actor of a token. active true sets it, false removes it, and without active it toggles. conditionId is the id from get-available-conditions or the name. On a linked token the condition lands on the actor and shows on all its tokens; that also needs the actor permission. Removing takes only the effects of that condition. The state is read back. level sets a condition with levels, such as frightened 2 in Pathfinder 2e or pain level 2 in DSA5, and 0 removes it; it needs an adapter for the game system that knows the levels.

List the conditions the game system of the world offers in Foundry, with id, name, icon and description. Use it to find the id for toggle-token-condition.

Put a roll button into the chat so a player rolls on their own device. Only that player and a Gamemaster can press it, and it rolls once. Whether the roll is PUBLIC (visible to all players) or PRIVATE (visible to the target player and the Gamemaster only) is a game decision: if the user did not say it, ask "Do you want this to be a PUBLIC roll or a PRIVATE roll?" and wait for the answer, then set isPublic and userConfirmedVisibility. targetPlayer is a player name or a character name. The formula comes from the adapter of the game system; without one, only rollType "custom" with a formula in rollTarget works. A player who is offline gets no request.

Create, change or delete an active effect on an actor, or on an item that actor carries. The effect fields go to Foundry as given, without game system rules; Foundry drops unknown fields, and the result lists every field that was dropped or stored differently. Find effect ids with get-character (effects of the actor) or get-character-entity (effects of an item). An effect that lies on an item is changed there, with parentType "item"; parentType "actor" never touches it. create and update need the actor permission "create and change", delete needs "create, change and delete", which is off by default. Every change is read back.

Describe, create, update or delete playlists. describe without playlist lists every playlist (like list-playlists); with playlist it returns that one with its tracks, and a unique part of the name is enough there. create checks every track first and creates the playlist with all tracks in one step. update changes fields of the playlist and of existing tracks; adding or removing tracks is not part of it. delete works by playlist id only, is refused while a scene still uses the playlist, and needs the playlist permission "create, change and delete". For changes a playlist is found by id or exact name (case ignored when unique), never by a part of the name.

Play or stop a playlist or one of its tracks, or switch its mode, through Foundry's own playback, so every connected browser follows. Playlist and track are found by id or exact name (case ignored when unique), never by a part of the name. The state is read back: a playlist without tracks or in mode "disabled" is an error, not a silent success. Browsers may only play sound after someone clicked on the page once. Needs the playlist permission "create and change".

Set or clear the playlist and the single track a scene plays when it is activated. A parameter left out keeps that field; null or an empty text clears it. playlist_sound alone picks a track of the playlist the scene already has. A new playlist keeps the track only when it belongs to it, otherwise the track is cleared and the result says so; the scene never points at a track outside its playlist. Scene, playlist and track are found by id or exact name (case ignored when unique). Needs the scene permission "create and change".

Replace the whole content of one text page, and optionally rename it, in one write. Content with HTML tags is stored exactly as sent. Plain text becomes paragraphs: a blank line starts a new paragraph, a single line break stays a break, and nothing is removed; Markdown is not converted, and the result says when the text looks like Markdown. Empty content is refused. The page is read back and compared; the result carries its length, not the content. To append instead, use journal-append-page. Needs the journal permission "create and change".

Create a journal that gives an overview of a campaign in several parts: progress, current part, location and quest giver, and for each part its levels, description and a status toggle. Clicking a toggle in Foundry cycles not started, in progress, completed, skipped and saves it on the journal; figures, current part and lock markers follow the saved status whenever the page is shown. A part is locked until the one before it is completed or skipped. The journal is visible to Gamemasters only, named after the campaign and placed in a journal folder with the campaign title (created when missing). Texts are written in the language of the Gamemaster's client.

Create a quest journal visible to Gamemasters only. Its first page holds the title and description, a background from location, quest giver and key figure, an overview with the given details, rewards and "Status: Active", an adventure hook as read-aloud text, a secret note for the Gamemaster, objectives from the quest type and the given facts, and a section for progress notes. All given values are escaped, so they appear as text. Write richer content yourself into additionalPages, which are stored as sent. Without folderName the journal is created outside any folder. The answer lists the pages with their ids and lengths, not the HTML.

Add a figure with its role to the list of related figures on the first text page of a quest journal. When an actor with this id or exact name exists in the world, the entry is a link to it; otherwise the name is written as text and the answer says so. Several actors with that name are an error listing their ids. The list is created once (in the overview of a page from create-quest-journal, else at the end of the page) and extended afterwards; the same figure in the same role is not added twice. The page is changed as a whole inside Foundry, so nothing of a long page is lost.

Write progress into a quest journal. Content that contains HTML tags is stored as sent; plain text is escaped and becomes paragraphs, with single line breaks kept. Markdown is not converted. Three ways:

• Without pageId and newPageName: a section with a heading for the update type and today's date is added to the progress notes of the first text page (a completion as read-aloud text, everything else as a secret Gamemaster note). completion and failure also set the status in the overview to Completed or Failed.

• With pageId: the content is appended to the end of that text page, without a heading.

• With newPageName: a new page with a heading and the content as a secret note. Content with its own heading gets no generated one. Pass pageId or newPageName, not both. Every write is read back and compared in full before success is reported; the answer gives the lengths before and after, not the HTML.

List every combat encounter of the world with its scene, whether it is active and started, round, turn, number of combatants and who acts now.

Read one combat encounter: the turn order with initiative, hidden and defeated flags, and the current turn with its actor (values from the game system adapter where there is one), token, conditions and who comes next.

Create a combat encounter on a scene (the active scene by default) and optionally add tokens as combatants. It does not start the encounter; start-combat does. Tokens are named by id only.

Add tokens to a combat encounter as combatants. Tokens come from the encounter's scene (for an encounter without scene: sceneIdentifier or the active scene). One unknown id stops everything; tokens already in the encounter are named and not added twice.

Remove combatants from a combat encounter, by combatant id or token id. Their initiative is lost; the tokens stay on the scene. One unknown id stops everything.

Set the initiative of a combatant (null clears it), hide it from players in the tracker, or mark it defeated. The acting combatant keeps its turn when the order changes. defeated is only the tracker flag; toggle-token-condition sets a condition.

Roll initiative with the game system's formula: for all combatants, only non player characters, or the combatants named. By default only those without initiative roll. Rolls are posted to the chat only with toChat; a hidden combatant is never posted publicly.

Start a combat encounter in round 1 with the first combatant of the turn order. A running encounter is left as it is and the answer says so.

Move a running combat encounter: next-turn, previous-turn, next-round, previous-round, or set-turn to a combatant. Moves use Foundry's own rules (for example skipping defeated combatants when the tracker is set so). The answer gives round and turn before and after.

End a combat encounter: it stops (round 0, not active) and keeps its combatants and initiatives. deleteEncounter deletes it instead, as Foundry's own End Combat does; deleting encounters is refused until they have a permission level.

Roll a free formula in Foundry, in any game system, e.g. "2d6+3" or "4d6kh3". Returns the total and every single die result. With actorId, @ references use that actor's roll data. Nothing is posted unless toChat is true.

Roll a check of the game system for an actor, such as ability, skill, save or attack. The formula comes from the game system adapter; in a system without one the answer is SYSTEM_NOT_SUPPORTED and roll-dice rolls a free formula. To let a player roll, use request-player-rolls.

Read the chat log as the Gamemaster sees it, newest first, whispers included, each with who it is whispered to. Filter by speaker, author, type, time or what one user can see, and page back with beforeId. Content is shown as plain text.

Post a message to the Foundry chat as the Gamemaster, or as an actor or token. Without whisperTo and whisperToGamemasters everyone sees it. Recipients are user ids or exact names; an unknown or ambiguous name sends nothing. Content is HTML.

Change the content or flavor of a chat message written by the Gamemaster the bridge runs as. Who sees the message does not change; send a new message for other recipients.

Delete a chat message written by the Gamemaster the bridge runs as, by id. Refused until the permission settings have a level for chat messages that allows deleting.

Read one roll table with its settings and every entry: id, range, weight, text and whether it is drawn. The entry ids are what update-roll-table needs.

Roll on a roll table and return the entries. mode "draw" follows the table: a table without replacement marks drawn entries so they do not come again. mode "roll" never marks anything. Nothing goes to the chat unless chat is set.

Return every drawn entry of a roll table, so all entries can be drawn again.

Change the settings and entries of a roll table: name, description, formula, replacement (false means drawn entries do not come again), displayRoll, change entries by id, add entries, remove entries by id. The whole result is checked before anything is written: overlapping ranges are refused, gaps are warnings. Removing entries needs the roll table permission set to full. Entry ids come from get-roll-table.

List the macros of the world with type (chat or script), folder, author and whether the AI may run them now. includeCommand shows the command text.

Create a macro. A chat macro holds chat text or a chat command such as /roll 1d20. A script macro holds JavaScript that can do anything a Gamemaster can once someone runs it. Creating runs nothing.

Run a macro in the Gamemaster's browser and report its result or error. Off by default: the world setting "macroExecution" must be "chat" for chat macros or "all" for script macros. A SCRIPT MACRO CAN DO ANYTHING a Gamemaster can, including deleting documents, and cannot be undone; read its command with list-macros first. A chat macro only posts to the chat.

List the walls (with doors), lights, sounds, regions (with behaviors), tiles and drawings of a scene, with ids and their main fields. Filter by type, by an area in pixels or to doors only. Works without a drawn canvas.

Create up to 200 elements of one type on a scene in one call, as Foundry data. Walls: c [x0, y0, x1, y1], door none, door or secret, doorState closed, open or locked, move none or normal, sight, light and sound none, limited, normal, proximity or distance, dir both, left or right. Lights: x, y, config { dim, bright, color, angle }. Sounds: x, y, radius, path. Tiles: x, y, width, height, texture { src }. Drawings: x, y, shape { type, width, height, points }. Regions: name, shapes, behaviors. One bad entry creates nothing. Needs the level "change" for scenes.

Change up to 200 elements of one type on a scene: each entry is { id, changes }, with Foundry fields and dotted keys such as "config.dim". Wall words as in create-canvas-elements. Every id is checked first; one unknown id changes nothing. Fields already holding the value are not written. Needs the level "change" for scenes.

Delete up to 200 elements of one type from a scene by id. Every id is checked first. Deleting needs the level "create, change and delete" for scenes, which is off by default; dryRun shows what would go and whether it is allowed.

Set doors (walls with door "door" or "secret") to open, closed or locked. Every id must be a door of the scene, else nothing changes. Players see the change at once. Needs the level "change" for scenes.

Whether the Gamemaster's browser has a drawn canvas, which scene it shows and which is active, the view position and zoom, and the Gamemaster's targets. Call it before pan-camera, ping-canvas or set-targets, which need the canvas.

Move the Gamemaster's view to a token or a point and set the zoom; with forEveryone, also pull every player viewing the scene to it (needs "Allow Write Operations"). Needs the drawn canvas in the Gamemaster's browser.

Show a ping at a token or a point to everyone viewing the scene, optionally pulling their views there. Needs "Allow Write Operations" and the drawn canvas in the Gamemaster's browser.

Replace the Gamemaster's targeted tokens on the viewed scene (ids or names); an empty list clears them. Players see the target marks, and later rolls use them. Needs "Allow Write Operations" and the drawn canvas.

Measure between two tokens or points, optionally via waypoints, in the scene's units and grid spaces, following the grid and the diagonal rule of the world. Token centers count. Works without a drawn canvas.

Test whether walls block the straight line between two tokens or points, for movement, sight, light or sound, and list the walls on it. Doors that are open do not block. Uses Foundry's own test when the canvas shows the scene, otherwise the stored walls.

Find a way from a token or point to another around walls that block movement (or sight, light, sound), on square and gridless scenes, and its length. Moves nothing; move-token moves a token. Works without a drawn canvas.

List the tokens within a distance (scene units) of a token or point, nearest first, optionally only those not hidden behind walls for sight. Works without a drawn canvas.

Take a picture of a scene so you can look at the map. Returns one image and, as JSON, every token with its number on the picture, name, grid cell, canvas position, size, disposition and hidden flag, plus the grid (type, cell size, distance) and how canvas pixels map to picture pixels. Grid labels on the picture count cells from 0 at the top left of the scene, the same numbers as the token list. When the GM views the scene, the rendered canvas is captured (background, tiles, drawings, token art; no lighting, fog or vision). Otherwise, or with mode "composed", the picture is the background with grid and numbered token markers. Read only.

Read Foundry's world time in seconds, formatted by the world's calendar when one is configured, and whether the game is paused.

Move the world time forward (or back with a negative number) by a number of seconds, through Foundry, so effects, calendars and modules react as at the table. 3600 is an hour and 86400 a day in the default calendar. The new time is read back. Needs the write switch.

Pause (paused: true) or resume (paused: false) the game for everyone. Needs the write switch.

Show a short notification (plain text, at most 500 characters) in Foundry to everyone or to chosen users, with the Gamemaster named as sender. Users are matched by id or exact name. Users who are not logged in do not get it, and it is not stored. Needs the write switch.

List the users of the world with role, whether they are logged in, their assigned character and the scene they are viewing. No passwords or access data.

Read registered world and client settings of the core ("core") or of chosen modules and systems, with name, scope, type and value. Values whose key looks like a secret are hidden, and the settings of this MCP module are not listed (get-permissions shows them). Client settings are those of the Gamemaster browser.

Change a world setting that is on the list of settings the AI may change (list-settings names the list; it is empty until the Gamemaster decides). Only text, number and true/false settings; the value is checked against choices and range and read back. Needs the write switch.

List folders and files in one folder of Foundry's data storage (source data, default) or of Foundry's own public files (source public). Paths are relative, such as "worlds//maps". Up to 500 entries each.

Create a folder in Foundry's data storage, with any missing folders above it. Never inside modules, systems or another world. An existing folder is left as it is. Needs the write switch.

Write a small file (at most 512 KiB) into an existing folder of Foundry's data storage, from text or from base64. An existing file is only replaced with overwrite: true. Scripts and HTML are never written, and Foundry accepts only its upload types. Never inside modules, systems or another world. Needs the write switch. Foundry cannot delete files; there is no tool for that.

Copy a file (at most 50 MiB) inside Foundry's data storage into an existing folder. The original stays: Foundry cannot delete files. To move files: find-file-references on the old path, copy-file, then world-rewrite-paths (dryRun first), then find-missing-files. Needs the write switch.

Find every field of every world document that points to a file or folder path, with the same path rule world-rewrite-paths uses: a folder matches the files under it, never a longer name. Use it before moving or replacing files. Compendiums are not scanned.

Find files that world documents point to but that do not exist: images, sounds, videos, text and fonts in fields and in markup, looked up in the data storage and in Foundry's own files. Wildcard paths are counted but not checked. Compendiums are not scanned.

List the card decks, hands and piles of the world with their card counts.

Read one card stack with its cards in order: name, suit, value, drawn, text, image and origin.

Create a card deck from a list of cards (or an empty hand or pile to deal into). Each card has a name and optionally text, image, suit and value. Read back with the cards in the given order.

Shuffle the cards of a stack through Foundry. Needs the write switch.

Draw cards from one stack (usually a deck) into another (usually a hand or pile). Refused before anything moves when too few cards are left. Every card is looked up afterwards. Needs the write switch.

Deal the same number of cards from one stack to each of several hands or piles. Refused before anything moves when too few cards are left. Needs the write switch.

Pass chosen cards from one stack to another, such as from a hand to a pile. Cards are named by id or by exact name within the source stack. Needs the write switch.

Reset a stack through Foundry: a deck takes back every card it gave out, from all hands and piles; a hand or pile returns its cards to their decks. Needs the write switch.

Delete a card stack by id. Card stacks have no level of their own in the permission settings yet, so deleting is refused until they get one.

Generic fallback: list documents of any type in the world, inside one document (parentUuid) or in a compendium (pack, read only), with conditions, sorting, paging and field selection. Prefer the specialised tools where one fits: list-journals, list-scenes, list-characters, list-compendium-entries, list-chat-messages, list-macros, list-playlists, list-roll-tables. Use this for types they do not cover (Combat, Cards, Wall, Region, Drawing), for game systems without an adapter, or to get exactly the fields needed. Without fields each row shows id, uuid, name, type and folder. describe-document-type shows the field paths.

Generic fallback: read one document of any type by uuid, or by documentType and id (with parentUuid for an embedded document, pack for a compendium), whole or only the given fields. A large answer comes in parts: call again with chunkStart and the fingerprint of the first part and join the parts. embedded "summary" shortens embedded collections to ids and names. Prefer get-character, get-current-scene, get-roll-table, get-compendium-item and get-token-details where they fit.

List the document types of this Foundry, or describe one: its fields from Foundry's data model, its subtypes, the system fields of a subtype in the active game system, what it holds and belongs to, the permission level writing it needs, the fields generic access never changes, and the specialised tools for it. Call it before creating or changing a type through generic access for the first time.

Generic fallback: create one document of any type in the world, or inside another document with parentUuid (a page in a journal, an item on an actor, a wall on a scene). data holds the fields as nested objects, as describe-document-type shows them. The permission settings apply as for the specialised tools; ids, ownership, _stats and the flags of this module cannot be given. The answer is read back from Foundry. Use dryRun first. Prefer journal-create, journal-add-page, create-scene, manage-actors, manage-world-items, create-macro and create-roll-table where they fit. Chat messages are sent only with send-chat-message; settings, users and compendiums are not written here.

Generic fallback: change fields of one document of any type. changes follows Foundry's update rules: keys may be dotted paths, an object merges into the object that is there, lists and other values replace it. A list position in a key ("system.skills.2.value") changes only that entry. replace names keys of changes whose object replaces the stored object instead of merging; remove names paths to delete. The answer is the change as read back from Foundry, and what was stored differently. Ids, ownership, _stats, the type, embedded collections, the flags of this module and what a specialised tool guards (active scene, playback, chat recipients, macro commands) cannot be changed here. Use dryRun first. Prefer update-scene, manage-actors, journal-set-page, update-token, update-roll-table, manage-effects and the other specialised tools where they fit.

Generic fallback: delete one document of any type, by uuid or by documentType and id. Needs the level "create, change and delete" of its kind, for an embedded document that of the document it belongs to; kinds without a level cannot be deleted. Refused for a folder with contents, a playlist or track a scene is linked to, the active scene and chat messages of others. dryRun shows what would go, embedded documents included. Prefer journal-delete, journal-delete-page, delete-scene, manage-actors, delete-playlist, delete-roll-table and delete-tokens where they fit. Compendium entries are deleted with delete-compendium-entries.

[Pathfinder 2e only] List, set, increase, decrease, remove or toggle a condition on an actor, with values such as frightened 2 or drained 1. pf2e keeps conditions as items with a value, which toggle-token-condition cannot set or read back; this tool writes through the system's own condition handling and reads the result back. A condition granted by another one (e.g. by grabbed) is removed with its source, not here. persistent-damage needs its damage and is applied on the sheet.

[DSA5 only] Find archetypes (ready made heroes of type character) in the actor compendiums of the dsa5 system, e.g. from the DSA5 core rules module, to create a hero with create-dsa5-character-from-archetype. Each archetype comes with id, name, compendium, species, profession and image. filterBySpecies matches the whole species ignoring case, filterByProfession a part of the profession ignoring case. A compendium that cannot be read is named with its cause.

[DSA5 only] Create one hero as a copy of an archetype from list-dsa5-archetypes, with a new name and optional details (age, biography, gender, eye and hair color, height, weight, species, culture, profession) written onto the hero and read back. The hero goes into the folder "Foundry MCP Actors", without a token in a scene, linked to its archetype. A name another actor has already (ignoring case) is refused. addToWorld false only prepares the hero and shows it, without writing anything.

[WFRP4e only] Change the stat block of an existing wfrp4e actor: initial, advances and modifier of characteristics, current and maximum wounds, advances of skills the actor already has, which career is current, movement and biography. Only given fields change; value, bonus and skill totals are recomputed by wfrp4e. Skills and careers match by name ignoring case; one that is missing or there twice is skipped and named in warnings, never guessed. Every value is read back; the answer lists old and new values, the new characteristic totals and anything stored differently. New skills, talents, trappings or careers: wfrp4e-add-items. A new actor: create-actor-from-compendium.

[WFRP4e only] Add skills, talents, traits, trappings, careers, weapons, spells and other items to an existing wfrp4e actor. Each name is looked up whole, ignoring case, in the item compendiums, wfrp4e-core first, and the entry is copied in full with a link to it. A specialised skill such as "Entertain (Taunt)" comes from its template "Entertain ()". A name that exists as several types is skipped with all candidates until "type" chooses; "pack" limits the search to compendiums whose id contains it. A name in no compendium becomes a blank item of "type" (trapping without it) and is listed in notFound. "advances" works for skills, "quantity" for gear, "setCurrent" for careers; elsewhere it is ignored with a warning. A skill or career the actor has already is skipped. Everything is read back. Change existing values with wfrp4e-update-actor.

List the changes the AI made to the world, newest first, from the change log of this session: when, by which Gamemaster, which tool, which documents, and whether each can be undone (and why not). Every entry has an id and the id of its tool call for undo-change. The log keeps the latest 200 changes and starts empty when the Gamemaster reloads the world.

Undo changes from the change log: one change (changeId), the changes of one tool call (callId, optionally only the last count of them), or without either the latest tool call that is not undone yet. Updates get their recorded fields back, created documents are removed (only if unchanged since), deleted documents are recreated with their old id. Refused as a whole, with the cause, when a change cannot be undone (chat messages, notifications, world time, pause, files, settings), when the permission level for the original change is missing, or when the documents changed since (force: true restores fields anyway, never removes). Every undo is itself logged; undo that entry to redo. Use dryRun first.