Embers: Tabletop RPG Toolkit

Update a character note (DM or player)

play_update_character_note

Idempotent

Update the DM-side or player-side note attached to a play character. PUT semantics — description replaces the current body. The player-side note (player-notes) is updated by the character's player (or an admin with Admin Mode on) or the campaign's GM; the DM-side note (dm-notes) by the campaign's GM alone, and a player gets 403. Triggers a notification (to the character owner if a GM updated, to GMs if a player updated). REQUIRES baseUpdatedAt: copy updatedAt from a fresh play_get_character_note read of the same note; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.

Input Schema

Name	Required	Description
`name`	No	Optional new name for the note.
`characterId`	Yes	Mongo `_id` of the play character (NOT the vault character id).
`description`	Yes	Note body markdown. PUT semantics: replaces the existing body.
`documentType`	Yes	Which note to update: 'dm-notes' or 'player-notes'.
`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.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 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 / 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 / characterId

Added value: +{
+  "description": "Mongo `_id` of the play character (NOT the vault character id).",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / description

Added value: +{
+  "description": "Note body markdown. PUT semantics: replaces the existing body.",
+  "type": "string"
+}

addedInput schema / properties / documentType

Added value: +{
+  "description": "Which note to update: 'dm-notes' or 'player-notes'.",
+  "enum": [
+    "dm-notes",
+    "player-notes"
+  ],
+  "type": "string"
+}

addedInput schema / properties / name

Added value: +{
+  "description": "Optional new name for the note.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / required

Added value: +[
+  "characterId",
+  "baseUpdatedAt",
+  "documentType",
+  "description"
+]

First observedSep 21, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds substantial context beyond them — concurrency control via baseUpdatedAt, the OUT_OF_SYNC failure with no partial write, the exact 403 authorization boundary, and notification side effects to owner/GMs. This is exactly the behavioral depth annotations cannot carry.

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

Conciseness5/5

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

Four dense sentences, each carrying distinct information (purpose, PUT semantics, permission matrix, concurrency requirement) with the core action front-loaded. No filler and no repetition of the title.

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?

With an output schema present the description needn't explain returns, and annotations cover the safety profile; the remaining risk areas for a mutation tool — authorization, optimistic concurrency, side effects, and the required read-then-write flow — are all covered.

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 description coverage is 100%, so the baseline is 3, but the description integrates the parameters into a workflow the schema states only in fragments: documentType is tied to the permission model, and baseUpdatedAt is framed as a copy-from-fresh-read proof with a named rejection error. The added value is real but largely reinforces the already-detailed schema descriptions, so it lands just above baseline.

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 ('Update the DM-side or player-side note attached to a play character') and immediately distinguishes the two note variants the tool operates on. The title's '(DM or player)' is expanded into a concrete scope, and the sibling play_get_character_note is named for the read counterpart, so the agent can route correctly without opening any schema.

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?

Explicit when-to-use with alternatives: it names play_get_character_note as the required preceding read, states the permission model per note type (player/owner/admin for player-notes; GM-only for dm-notes with a 403 otherwise), and defines PUT replacement semantics. Nothing about selecting or invoking the tool correctly is left to inference.

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?