Embers: Tabletop RPG Toolkit

Update a vault character

vault_update_character

Idempotent

Patch fields on an existing character by id. Only supplied fields change, with one distinction: object sub-docs (defense, core, offense, speed, personality, settings) deep-merge — nested keys you omit are preserved — but ARRAY fields (items, spells, rules, skills, actions, trackables, attributes, notes) are atomic: the array you send replaces the stored array wholesale. To add or edit one array entry, vault_get_character first, modify the returned array, and send the complete array back. Sending null for a field is treated the same as omitting it (the field keeps its current value) — null does NOT clear; to clear a text field send an empty string. This is also the canonical tool for editing a play campaign character's HP, conditions, or inventory; play characters are pointers to vault characters and play has no direct character-write endpoint. AC caution (5e24): when the character's settings.autoPassiveBonuses is true (the default for new 5e24 characters), the armor and shield rows of defense.armorClass are derived from equipped items and recomputed on every sheet load — change AC by setting equipped on the character's armor/shield items, not by writing those rows; when the toggle is false, defense.armorClass is manually authored and writing it directly is correct. Caution: mutations may affect any active play campaign or expedition referencing this character. Consider running vault_get_character first to inspect linkage. REQUIRES baseUpdatedAt: copy updatedAt from a fresh vault_get_character read; 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. companions is NOT writable here (it is stripped): manage buddy ties with vault_attach_companion / vault_detach_companion, and a linked buddy's tracked values with vault_update_companion_state. linkGroup is NOT writable here either (also stripped): linked-sheet group membership is created by vault_spawn_linked_character and only vault's unlink endpoint clears it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Output Schema

TableJSON Schema

Name	Required	Description	Default
`_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 21, 2026

TDQS

A5/5.0

Behavior5/5

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

The description discloses deep-merge vs atomic array semantics, null-as-omit behavior, the AC 5e24 derivation caveat, side effects on active play campaigns, the baseUpdatedAt concurrency requirement, and stripped fields. This vastly exceeds what the sparse annotations provide, with no contradictions.

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?

It is long, but every section earns its place given the tool's complexity: merge rules, null handling, the AC exception, concurrency, play-character scope, and non-writable fields are all dense, non-redundant warnings an agent needs. The core action is front-loaded.

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 mutation tool with no real input schema and minimal annotations, the description is remarkably complete: it covers preconditions, failure modes, side effects, and routing to sibling tools. An output schema exists, so return-value details are not required here.

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

Parameters5/5

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

Although the input schema exposes zero properties and coverage is 100%, the description supplies essential semantic context: baseUpdatedAt is required and must come from a fresh read, field-level merge behavior is defined, and clear values are explained. It fully compensates for the absence of a useful schema.

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: 'Patch fields on an existing character by id.' It also distinguishes itself from related tools by declaring this is the canonical tool for editing play campaign character HP/conditions/inventory and by stating what is intentionally NOT writable here.

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?

It provides explicit when-to-use guidance, including the play-character exception and alternatives for companion/link management. It also instructs the agent to read vault_get_character first, both for linkage inspection and to obtain a fresh baseUpdatedAt.

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?