Embers: Tabletop RPG Toolkit

Update an adventure page

imagine_update_adventure_page

Idempotent

PUT updates to one adventure page by id. Only supplied fields are sent; every field on the AdventurePage shape (name, content, summary, image, documentType, tags, parentId, link, menuOrder, aliases, details, worldPageRefs, vaultRefs, treasureRefs, scene-shape goal/duration, location-shape locationKey/map/mapPin) can be updated through this tool. Read-aloud / moving-on / tactics are NOT fields — author them inline in content as [[read-aloud]] / [[moving-on]] / [[tactics]] callout blocks. Caller must have 'edit'. WARNING about content: imagine REPLACES the body with whatever you send. To fix wording inside an existing body without losing formatting whitespace, prefer imagine_replace_in_adventure_page (surgical). To append, fetch the page first with imagine_get_adventure_page (raw=true), concatenate, and send the combined body back. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_adventure_page read of this page; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written — writing from memory of an earlier read is not possible.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Adventure page id.
`map`	No	Location shape: Mongo `_id` of the Map this location belongs to. Pass null to clear.
`goal`	No
`link`	No	URL-safe slug. Lowercase letters, numbers, hyphens, slashes.
`name`	No	Page name.
`tags`	No	Tag list. Imagine stores as a comma-separated `keywords` string.
`image`	No
`active`	No
`mapPin`	No
`aliases`	No
`content`	No	Page body in markdown. Imagine renders this verbatim. WARNING: REPLACED wholesale on update; prefer imagine_replace_in_adventure_page for surgical edits.
`details`	No	Label/value list of arbitrary metadata pairs.
`summary`	No	Short page summary. Max 150 characters (matches the AdventurePage Mongoose schema's maxlength). Sibling Adventure and WorldPage summaries share the same cap; legacy World summaries cap at 255 (cross-app convention).
`duration`	No
`parentId`	No	Mongo `_id` of the parent page (for tree structure).
`template`	No	Template id when authored from a template.
`menuOrder`	No
`vaultRefs`	No	Participants on the page. Each entry `{ vaultId?, type?, count?, name? }`.
`locationKey`	No
`documentType`	No	Structural type. Drives shape-specific fields.
`treasureRefs`	No	Treasure entries. Same shape as `vaultRefs`.
`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.
`outboundLinks`	No	AdventurePage ids this page links to. Imagine recomputes this on save when missing; explicit values override.
`relationships`	No	Sibling AdventurePage ids the page relates to.
`worldPageRefs`	No	Mongo `_id` list of referenced world pages.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed28 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 / aliases

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "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 / content

Added value: +{
+  "description": "Page body in markdown. Imagine renders this verbatim. WARNING: REPLACED wholesale on update; prefer imagine_replace_in_adventure_page for surgical edits.",
+  "type": "string"
+}

addedInput schema / properties / details

Added value: +{
+  "description": "Label/value list of arbitrary metadata pairs.",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "label": {
+        "type": "string"
+      },
+      "value": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / documentType

Added value: +{
+  "description": "Structural type. Drives shape-specific fields.",
+  "enum": [
+    "generic",
+    "act",
+    "scene",
+    "location",
+    "character",
+    "handout",
+    "lore",
+    "appendix",
+    "map"
+  ],
+  "type": "string"
+}

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

addedInput schema / properties / id

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

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

addedInput schema / properties / link

Added value: +{
+  "description": "URL-safe slug. Lowercase letters, numbers, hyphens, slashes.",
+  "type": "string"
+}

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

addedInput schema / properties / map

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Location shape: Mongo `_id` of the Map this location belongs to. Pass null to clear."
+}

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

addedInput schema / properties / menuOrder

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / name

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

addedInput schema / properties / outboundLinks

Added value: +{
+  "description": "AdventurePage ids this page links to. Imagine recomputes this on save when missing; explicit values override.",
+  "items": {
+    "description": "Mongo `_id` reference (24-character hex string).",
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / parentId

Added value: +{
+  "description": "Mongo `_id` of the parent page (for tree structure).",
+  "type": "string"
+}

addedInput schema / properties / relationships

Added value: +{
+  "description": "Sibling AdventurePage ids the page relates to.",
+  "items": {
+    "description": "Mongo `_id` reference (24-character hex string).",
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / summary

Added value: +{
+  "description": "Short page summary. Max 150 characters (matches the AdventurePage Mongoose schema's maxlength). Sibling Adventure and WorldPage summaries share the same cap; legacy World summaries cap at 255 (cross-app convention).",
+  "maxLength": 150,
+  "type": "string"
+}

addedInput schema / properties / tags

Added value: +{
+  "description": "Tag list. Imagine stores as a comma-separated `keywords` string.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / template

Added value: +{
+  "description": "Template id when authored from a template.",
+  "type": "string"
+}

addedInput schema / properties / treasureRefs

Added value: +{
+  "description": "Treasure entries. Same shape as `vaultRefs`.",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "count": {
+        "type": "number"
+      },
+      "name": {
+        "type": "string"
+      },
+      "type": {
+        "type": "string"
+      },
+      "vaultId": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / vaultRefs

Added value: +{
+  "description": "Participants on the page. Each entry `{ vaultId?, type?, count?, name? }`.",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "count": {
+        "type": "number"
+      },
+      "name": {
+        "type": "string"
+      },
+      "type": {
+        "type": "string"
+      },
+      "vaultId": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / worldPageRefs

Added value: +{
+  "description": "Mongo `_id` list of referenced world pages.",
+  "items": {
+    "description": "Mongo `_id` reference (24-character hex string).",
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / required

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

First observedSep 21, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already signal this is a write operation, but the description adds substantial behavioral detail: only supplied fields are sent, content is replaced wholesale, stale baseUpdatedAt values are rejected with OUT_OF_SYNC and nothing is written, and successful updates return a new updatedAt. It also discloses that read-aloud/moving-on/tactics are not fields but must be authored inline as callout blocks, which is valuable beyond the schema and 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?

The description is long but information-dense, with the core verb, resource, and warnings front-loaded before alternatives and prerequisites. Every major sentence earns its place, though the long field enumeration and repeated warning about content could arguably be tightened without losing value.

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 25-parameter write tool with concurrency requirements and several nearby siblings, this description is unusually complete: it covers update semantics, the wholesale-content hazard, the required optimistic-locking workflow, the permission requirement, and the correct alternative for surgical edits. An output schema exists, so the absence of return-value detail is acceptable.

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

Parameters4/5

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

Schema coverage is 68%, so the description does not need to fully re-document parameters, but it adds important meaning beyond the schema: the warning that content is replaced wholesale, the detailed required meaning of baseUpdatedAt, and the clarification that read-aloud/moving-on/tactics are not fields. It does not deeply explain the handful of parameters lacking schema descriptions, but it compensates reasonably for the main risk areas in an update tool.

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?

The description opens with a specific verb and resource ('PUT updates to one adventure page by id') and goes on to enumerate the full set of updateable fields, which clearly differentiates it from sibling get/create/replace tools. It also names the sibling surgical alternative, so an agent can distinguish this tool from imagine_replace_in_adventure_page without inspecting schemas.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool versus alternatives: prefer imagine_replace_in_adventure_page for surgical content edits, and fetch via imagine_get_adventure_page with raw=true when appending. It also states the required permission ('Caller must have edit') and the mandatory fresh-read workflow for baseUpdatedAt, giving unambiguous selection and invocation guidance.

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?