Embers: Tabletop RPG Toolkit

Update an adventure

imagine_update_adventure

Idempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Adventure id.
`link`	No	URL-safe slug. Lowercase letters, numbers, and hyphens. Imagine auto-suggests at create time when omitted.
`name`	No	Adventure name.
`image`	No	Header image URL.
`level`	No	Recommended character level range. Each side optional; null means unset.
`world`	No	Optional World _id this adventure belongs to.
`active`	No
`parent`	No	Series grouping: `_id` of the umbrella adventure this adventure is one part of. Depth is capped at one level — the parent cannot itself be a part, and an adventure that has parts cannot become a part (400 either way). The parent must be active and viewable by the caller (owner / contributor / public / stock), else 404. Pass null (or '') to clear. Setting a NEW parent without `menuOrder` appends the adventure to the end of the series.
`public`	No
`status`	No
`ruleset`	No	Ruleset code, from list_rulesets. Required at create.
`summary`	No	Short summary; capped at 150 characters by imagine.
`version`	No
`keywords`	No	Comma-separated keyword string used by adventure-wide tag/search.
`barImages`	No	GM-curated reference images displayed in a fixed bar across the adventure (maps, handouts, NPC portraits).
`menuOrder`	No	Sort position among sibling parts of the same series parent. Send alone to reorder an existing part; omit when setting `parent` so the server appends to the end.
`partySize`	No	Recommended party size range.
`publisher`	No
`companions`	No
`description`	No	Full adventure description. Markdown supported.
`baseUpdatedAt`	Yes	REQUIRED proof that you are working from the latest version: copy the `updatedAt` value verbatim from a FRESH read of this exact record (use the matching get tool first). Values from memory, from an earlier conversation, or guessed timestamps are rejected with OUT_OF_SYNC and nothing is written. After a successful update, the response carries the new `updatedAt` — use that for any follow-up write.
`imageCarousel`	No
`estimatedHours`	No
`contentWarnings`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 27, 2026

changedInput schema / properties / ruleset / description

Previous value: -"Ruleset code (e.g. '5th Edition', '5e24', 'PFRPG'). Required at create."New value: +"Ruleset code, from list_rulesets. Required at create."

Changed27 schema fields changedSep 25, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +{}
```
addedInput schema / properties / active
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / barImages

Added value: +{
+  "description": "GM-curated reference images displayed in a fixed bar across the adventure (maps, handouts, NPC portraits).",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "url": {
+        "description": "Image URL. Required by Mongoose; gateway leaves it optional so a missing url surfaces as a clean backend error.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / baseUpdatedAt

Added value: +{
+  "description": "REQUIRED proof that you are working from the latest version: copy the `updatedAt` value verbatim from a FRESH read of this exact record (use the matching get tool first). Values from memory, from an earlier conversation, or guessed timestamps are rejected with OUT_OF_SYNC and nothing is written. After a successful update, the response carries the new `updatedAt` — use that for any follow-up write.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / companions

Added value: +{
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "type": {
+        "type": "string"
+      },
+      "vaultId": {
+        "description": "Vault entity id (character/monster). Required by Mongoose.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / contentWarnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / description

Added value: +{
+  "description": "Full adventure description. Markdown supported.",
+  "type": "string"
+}

addedInput schema / properties / estimatedHours
```
Added value: +{
+  "type": "number"
+}
```

addedInput schema / properties / id

Added value: +{
+  "description": "Adventure id.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / image

Added value: +{
+  "description": "Header image URL.",
+  "type": "string"
+}

addedInput schema / properties / imageCarousel

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / keywords

Added value: +{
+  "description": "Comma-separated keyword string used by adventure-wide tag/search.",
+  "type": "string"
+}

addedInput schema / properties / level

Added value: +{
+  "additionalProperties": {},
+  "description": "Recommended character level range. Each side optional; null means unset.",
+  "properties": {
+    "max": {
+      "type": "number"
+    },
+    "min": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / link

Added value: +{
+  "description": "URL-safe slug. Lowercase letters, numbers, and hyphens. Imagine auto-suggests at create time when omitted.",
+  "type": "string"
+}

addedInput schema / properties / menuOrder

Added value: +{
+  "description": "Sort position among sibling parts of the same series parent. Send alone to reorder an existing part; omit when setting `parent` so the server appends to the end.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / name

Added value: +{
+  "description": "Adventure name.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / parent

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Series grouping: `_id` of the umbrella adventure this adventure is one part of. Depth is capped at one level — the parent cannot itself be a part, and an adventure that has parts cannot become a part (400 either way). The parent must be active and viewable by the caller (owner / contributor / public / stock), else 404. Pass null (or '') to clear. Setting a NEW parent without `menuOrder` appends the adventure to the end of the series."
+}

addedInput schema / properties / partySize

Added value: +{
+  "additionalProperties": {},
+  "description": "Recommended party size range.",
+  "properties": {
+    "max": {
+      "type": "number"
+    },
+    "min": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / public
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / publisher
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / ruleset

Added value: +{
+  "description": "Ruleset code (e.g. '5th Edition', '5e24', 'PFRPG'). Required at create.",
+  "type": "string"
+}

addedInput schema / properties / status

Added value: +{
+  "enum": [
+    "draft",
+    "playtest",
+    "published"
+  ],
+  "type": "string"
+}

addedInput schema / properties / summary

Added value: +{
+  "description": "Short summary; capped at 150 characters by imagine.",
+  "maxLength": 150,
+  "type": "string"
+}

addedInput schema / properties / version
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / world

Added value: +{
+  "description": "Optional World _id this adventure belongs to.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / required

Added value: +[
+  "id",
+  "baseUpdatedAt"
+]

First observedSep 21, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond them: partial-update semantics, the 'edit' permission requirement, optimistic-concurrency via baseUpdatedAt with OUT_OF_SYNC and 'nothing is written' on failure, and rename propagation to linked campaigns. This is exactly the context an agent cannot get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb+resource, then permission, then the two highest-risk behaviors (series grouping, baseUpdatedAt). Dense but every sentence carries operational weight; only the parent clause is slightly redundant with the field description it points to.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 24-param mutation tool with an output schema and rich annotations, the description covers the contract-completing details an agent needs: partial update, auth, concurrency guard, and side effects on linked campaigns. Return values are covered by the output schema, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 24 parameters and only 63% schema description coverage, the schema does most of the heavy lifting. The description adds real value for the tricky parameters (baseUpdatedAt workflow, parent grouping/ungrouping, menuOrder append default) but explicitly defers to the field description for parent validation and does not address the remaining undocumented fields. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('PUT updates to one adventure by id') and is clearly distinguishable from siblings like imagine_update_adventure_page and imagine_create_adventure. The scope of a partial update ('Only supplied fields are sent') is stated up front, so an agent knows exactly what this tool mutates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear prerequisites and routing: caller needs 'edit', and it explicitly directs the agent to a fresh imagine_get_adventure read before calling, with the OUT_OF_SYNC failure described. It does not spell out when to prefer a sibling like imagine_update_adventure_page, but for the common case the when-to-use is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Embers: Tabletop RPG Toolkit tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?