Read campaign identity, role, health, current map, and capability evidence. Use this for orientation; use map_list for all maps and session_list for sessions. Read-only for campaign members; /health reachability is not feature support, and unprobed capabilities remain unknown. Repeating reads does not change game state. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read persisted campaign messages with opaque cursor pagination. Use chat_read for narration history; use events_poll for dice results and live events. Read-only for campaign members. Start without a cursor, then pass nextCursor unchanged; stop at null. Older servers support only the latest page and reject cursor history. DICE_ROLL entries are excluded. Repeated reads do not consume messages. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read buffered campaign events and asynchronous write errors without consuming them. Use after WS writes; use chat_read for persisted chat history. May connect WS lazily, but does not change game state. Returns earliest seq > since first; advance using next_seq (latest_seq is its alias), not high_water_seq. Check gap for eviction from the 500-event buffer, cursor_reset after process restart, and has_more for pagination. Inspect system.error and relevant state to assess pending writes; broadcasts are not correlated ACKs. Buffered events remain available on connection failure, marked stale; this is not durable dice history. Repeated reads can include newly arriving events. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List maps accessible in the configured campaign to choose a map ID and inspect dimensions. Use map_switch to activate one; listing does not switch maps or place tokens. Read-only for campaign members; repeated calls leave game state unchanged. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read initiative state without changing turn order or advancing combat. Use initiative_manage to modify combat and events_poll for broadcast history. Campaign members may read. By default, request a new WS state and wait up to two seconds; timeout returns state=null/stale=true, not proof that combat is inactive. refresh=false reads the current connection's cache and marks it stale. Repeated requests do not change initiative; WS authentication is still required. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List the configured campaign roster to discover character IDs and assignments. Use character_get for one full sheet or character_create to add a sheet. Read-only for campaign members; no creation or roster changes occur on repeat calls. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read a full character sheet by ID, preserving unknown fields. Use character_list to discover roster IDs and character_update to patch a sheet. Upstream allows the owner or campaign members to read; keeper data.notes are not private DM fields. Interpret data using the character's own gameSystem, preserving CoC fields and DND hitDice structures. Repeated reads do not alter the sheet. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read upstream validation diagnostics for an owned character with a fixed gameSystem. Use character_get to inspect fields; do not use this as a reliable save gate. v1.4.0 ignores validation failures, so isValid=true does not prove validity; older-version reliability is unknown. Always adds validation_reliable=false and validation_note. Owner-only upstream read; repeating it does not repair or save data. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Search library templates for later placement with token_place_creature. Use character_list for campaign character sheets; this does not create either a character or a token. Read-only for campaign members. Explicit srd requires DND_5E; custom works across systems. Empty source searches both in DND_5E and custom otherwise. Search, challenge rating and offset are forwarded; limit is capped at 100 without local lower-bound validation. Repeating a search leaves the library unchanged. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Post one campaign chat message as narration or player dialogue. Use chat_read to inspect history; use dice_roll for dice, not chat text pretending to be a roll. Authenticated campaign membership is required; type is a message category, not a role grant. Upstream campaign chat cooldown may reject messages. Creates a new message on each accepted send; do not retry blindly. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Roll server-authoritative dice and publish the result to the permitted audience. Use saved_roll_list for stored expressions; saving a macro does not execute it. Authenticated campaign users may roll. Public rolls broadcast to the campaign; v1.4.0 secret rolls go to the roller and DMs, not exclusively to DMs if a player rolls. Each send creates a new roll; never retry on missing results. Calls queue with a 2.1-second minimum between actual sends; upstream allows 30 rolls/minute/user. The bridge performs no random generation or rules calculations. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Set the current campaign map through REST, then notify via WS map.change (DM only). Use map_list to choose an existing map; token_move changes a token, not the active map. REST persistence and WS dispatch are separate: persisted=true does not prove clients received the change. A WS failure returns ok=false with data.persisted=true; do not replay or roll back the saved change. Broadcast receipt remains sent=true, confirmed=false,status="pending"; inspect events_poll for results/errors, not an ACK. Repeating may repeat notifications even when the current map is already correct. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Create a manually configured token on a campaign map (DM only). Use token_place_creature for a library template's name/image, token_move for an existing token, and character_create when a new sheet is needed. This creates only a token; character_id optionally links an existing sheet. Position uses map units; upstream checks map bounds and layer. Width/height are integer sizes in 1..10. visible and controlled_by govern display/control subject to server permissions. REST returns persisted=true,broadcast_confirmed=false; inspect events_poll or the VTT for visibility, since persistence does not confirm a broadcast. Every accepted call creates another token, so repeated calls are not idempotent. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Set an existing token's absolute position through REST. Use token_add to create a token or map_switch to change the active map. The bridge rejects SPECTATOR/unknown roles; upstream requires DM or the controlling player. The same coordinates produce the same position, but repeated writes may produce notifications. Returns persisted=true,broadcast_confirmed=false; REST does not itself emit map.changed. Inspect events_poll or the VTT before assuming others saw the move; this result is not a correlated broadcast ACK. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Apply a signed HP delta to a character sheet through WS, not to a token ID. Use character_get to inspect HP or character_update for an absolute sheet patch. Upstream requires character ownership or DM authority and campaign assignment; its system-specific HP rules determine the result. Positive delta heals, negative delta damages. Repeating applies the delta again and is not idempotent. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Modify campaign combatants, initiative values, order, or combat lifecycle. Use initiative_read for current state and events_poll for results/errors. Structural actions are DM-only; v1.4.0 also permits a controlling player to roll for an already added token before combat, subject to upstream checks. Older permission behavior is unverified. Actions may remove entries, clear state, reroll, or advance turns; the combined tool is not idempotent. add needs token_id/map_id; remove needs token_id; set needs token_id/map_id/value; reorder needs ordered_token_ids; start/next/end need only action. roll needs token_id and map_id and is gated to DND_5E/PATHFINDER_2E/SHADOWRUN_6E. The server derives system rolls; expression is a DM fallback, not a guaranteed override. CoC7e uses DEX ordering: use add/start or set. The dice_roll 2.1-second queue does not wrap initiative_manage; do not assume it throttles initiative rolls. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Patch an existing sheet while preserving unspecified fields (owner or campaign DM). Use character_get first; use token_hp_update for a signed HP change and character_create for a new sheet. data is a request-field object, e.g. {"data":{"hp":{"current":5}}}. Only name/data/tokenImageUrl are allowed at the top level. Nested data dictionaries merge recursively after a GET; arrays/scalars replace whole values and null is an explicit value, not deletion. The caller calculates rules values using the sheet's own gameSystem. Updates are locked only within this process; concurrent browser saves may be lost. Reapplying values is stable absent concurrent edits, but upstream update side effects are not guaranteed idempotent. REST errors retain diagnostics. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Create a character sheet and ensure it appears in the current campaign roster. Use character_update for an existing sheet and token_add to place a linked token; creation does not place one. Campaign gameSystem determines the initial schema; upstream validates membership and sheet data. Do not trust character_validate as a save gate. After POST, the bridge reads the roster and assigns only if not found. This is not atomic or idempotent: assignment failure returns ok=false with the created character ID in data; missing ID means creation status is unknown. Inspect the roster/UI and recover the existing sheet instead of creating a duplicate. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Create a visible 1x1 token from a library template's name and image (DM only). Use creature_search to obtain a template ID; use token_add for custom size, layer, controller, visibility, or a character link. This reads the template and copies only name/image into a token: it does not create a sheet or copy creature stats. Fails before creation if no usable image exists. Position must be within the map. Each accepted call creates another token. Returns upstream REST data without a broadcast receipt; use events_poll or the VTT to inspect subsequent visibility. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Start, pause, or end a campaign session through REST (DM only). Use session_list to inspect history and session_notes_update to edit or clear a recap without another lifecycle transition. start creates a session; pause/end resolve campaign.activeSession.id and fail if none exists. Lifecycle changes are not guaranteed idempotent: do not repeat start/end to repair notes. notes and save_state apply only to end; other actions reject nondefault values. End notes are campaign-wide, and empty text does not clear an existing recap. save_state requests the upstream end-of-session snapshot; it is not a bridge-side backup. Returns upstream REST data; it does not wait for a WS business ACK. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Create a campaign map using existing image assets (DM only). Use map_list to inspect existing maps and map_switch to activate one; creation does not switch the current map. This creates a map with empty tokens and annotations, not an uploaded image. Upstream checks image access and normalizes asset URLs. Each accepted call creates another map; do not blindly retry an uncertain result. Returns upstream {map} in data without a broadcast receipt. REST validation and permission errors retain upstream diagnostics. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Delete a campaign map and its stored tokens and map state (DM only). Use map_list to inspect maps first; use map_switch to select another current map before deletion. Upstream rejects deletion of the current map with HTTP 400. Use token_delete to remove only one token instead of the entire map. Deletion is destructive and has no undo tool. Repeating leaves the map absent but may return a not-found error. Returns upstream {message} in data without a broadcast receipt; REST permission and resource errors retain upstream diagnostics. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Delete one token from a campaign map (DM only). Use token_move to reposition a token instead. Use token_hp_update for a signed sheet HP adjustment through WS: that tool takes a character ID, whereas this tool takes a map token ID. Deletion removes the placed token, not its linked character sheet or HP, and does not manage initiative entries. It is destructive and has no undo tool. Repeating leaves the token absent but may return a not-found error. Returns upstream {message} in data without a broadcast receipt; REST permission and resource errors retain upstream diagnostics. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Delete a character sheet permanently (owner only). Use character_get to inspect the sheet first and character_update to edit it; use token_delete to remove only a placed map token. This deletes the sheet itself, not just its campaign assignment. DM authority alone does not grant deletion rights. It has no undo tool and does not remove map tokens. Repeating leaves the sheet absent but may return a not-found error. Returns upstream {message} in data; REST permission and resource errors retain diagnostics. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Upload an existing local PDF/txt/md file as a document asset using multipart REST. Use document_create for inline text, or document_share to link an existing asset. Reads the MCP server/container filesystem; client-local paths must be mounted. Creates an asset on each accepted call, so retries may duplicate it. Scope controls access: CAMPAIGN requires that campaign's DM; other scope rights are upstream-enforced. The server checks signatures and its size cap (default 50 MiB), with a shared upload/create limit of 30/minute/user by default. A 400 is preserved without fallback upload. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Create a new txt/md document from inline content through REST. Use document_upload for PDF or larger local files, and document_update to replace existing text. Name and description are trimmed; content preserves whitespace. USER is personal, CAMPAIGN requires its DM, and GLOBAL rights are enforced upstream. Each accepted call creates a separate asset. Content is capped at 900 KiB UTF-8; upstream JSON limits also apply. Upload/create share a default 30 requests/minute/user limit. Creation does not separately link a personal asset; use document_share for that. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List document assets with scope, search, and page filters. Use campaign_document_list to discover personal documents shared into this campaign; use document_read for content. Read-only; upstream filters by access. USER restricts to personal assets (including an explicit current-user filter for admins); null scope leaves filtering to upstream. Repeated listing does not consume or modify assets. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List native and shared documents visible in the configured campaign. Use document_list for asset-library filters and document_read for content. Read-only for members. shared=false identifies a native document without a separate link to revoke; document_unshare cannot remove that source of access. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Read an accessible document as text or a local binary download. Use document_list/campaign_document_list to discover IDs; use document_update to replace txt/md content. Upstream checks asset visibility, including shared access. Does not modify upstream data, but binary reads atomically replace downloads/.pdf (or .bin) locally; readOnlyHint refers to the upstream resource. Text returns mime_type/etag/content. Binary returns mime_type/etag/file_path/file_size, never inline bytes. Pass etag unchanged for a conditional read: 304 returns not_modified=true without content, so retain your cached copy. Repeated reads may refresh the local file. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Replace an entire txt/md document's content (uploader/admin only). Use document_read first to avoid losing text; use document_create for a new asset or document_upload for PDF. This is replacement, not merge-patching, and cannot edit PDF content. Empty content clears the text. Repeated writes can update metadata or notifications; no full-operation idempotency is promised. Returns upstream REST data. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Link a shareable document asset into the configured campaign (DM only). Use campaign_document_list to inspect existing links, or document_upload to create an asset first. Upstream validates asset ownership, UUID, and sharing rights. Sharing broadens access without copying the asset. Duplicate-link behavior is upstream-controlled; do not assume retries are idempotent. Use document_unshare to revoke this link, not document_delete, which removes the asset everywhere. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Remove one document share link from the configured campaign (DM only). Inspect campaign_document_list first: shared=false denotes a native document with no separate link to revoke. Use document_delete only to delete the asset everywhere. This leaves the asset, other links, local downloads, and GLOBAL/native read access intact. Repeating removes no additional link but may return a not-found error. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Delete a document asset and all of its share links. Use document_unshare to remove only one campaign link and document_read to inspect content first. Upstream enforces uploader/DM/admin permissions according to scope. Deletion is destructive; local downloaded copies remain. Repeating leaves the asset absent but can return a not-found error. This tool does not offer an undo operation. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List complete Saved Roll macros owned by the current user in this campaign. Use dice_roll with a returned expression to execute it, or saved_roll_update to edit. Read-only for campaign members; no individual get is needed and no dice are rolled. Repeating the list does not consume macros. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Save a private dice-expression macro for the current user and campaign. Use dice_roll to execute an expression; use saved_roll_update to edit an existing macro without creating another. Members manage only their own macros. The server parses expressions and limits each user to 50 per campaign. Creation is serialized only within this process; each accepted call may create another macro. No dice are rolled and no campaign-visible message is sent by this tool. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Change the name or expression of your Saved Roll in this campaign. Use saved_roll_list to find its ID; use dice_roll to execute it. Supply at least one field; null leaves that field unchanged. Upstream validates expressions and enforces per-user/per-campaign ownership. Replacing values does not roll dice; repeated writes may change update metadata, so full-operation idempotency is not guaranteed. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Delete your Saved Roll from the configured campaign. Use saved_roll_list to identify it or saved_roll_update to change it without deletion. Any member may delete their own macro; cross-user/cross-campaign access returns 404. Destructive to the macro only, not roll history. Repeating leaves it absent but may return a not-found error; it does not roll dice. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Transfer the campaign DM role to an existing member, or reclaim it as owner. Use campaign_get to inspect current role/ownership first. Upstream permits DM, owner, or admin; owner reclaim uses the owner's own ID. The old DM becomes PLAYER, ownerId stays unchanged, and local role/system caches are invalidated after success. Do not simulate this with separate role edits. Role changes and broadcasts are not guaranteed idempotent; inspect campaign_get before considering another transfer. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Spend one remaining use from a DND_5E character's Hit Dice pool through WS. Use character_get to inspect pools first; dice_roll and token_hp_update perform rolling and healing separately, with no shared transaction. Upstream requires the character owner or DM and campaign assignment. index selects an array entry, not a dice count. Repeating spends again. Only the system is gated locally: there is no reliable capability probe, and older servers may silently ignore this event. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

List this campaign's latest 50 sessions in descending sessionNumber order, including active sessions. Use session_manage for lifecycle changes and session_notes_update for recaps. Read-only for members; notes are shared with all members, and repeated reads do not end or resume sessions. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Replace a session's shared recap without another lifecycle transition (DM only). Use session_list to find the ID; use session_manage to start/pause/end instead. All campaign members can read notes. Empty text after upstream trimming clears the recap, unlike empty notes on session_manage end. Does not end the session or broadcast a recap event. Repeated writes may alter metadata, so full-operation idempotency is not guaranteed. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.