Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Preview converting a character to its ruleset's successor

vault_preview_character_conversion
Read-onlyIdempotent

Preview the version vault would make, in the ruleset that succeeds its own, of a character the user may edit (their own, or any for an admin with Admin Mode on). Creates nothing. Vault decides which rulesets convert and to which: the result's ruleset is { from, to } (codes; list_rulesets has their labels), and a character of a ruleset with no successor answers 409. The conversion makes a new version of the same character as its linked sheet in ruleset.to, beside the untouched original: it translates the sheet's records and keeps its numbers (ability scores, hit points, skills), and it is not a rules rebuild. The conversion asks the user nothing: vault makes every choice and reports it, and anything the user disagrees with they change on the new sheet afterward. Returns character ({ _id, name, updatedAt }), ruleset, fills (the blank linked sheet that will be filled in, or null when a new character will be made), and report, the forecast of what the conversion will do: { sections: [{ key, title, count, rows }] }, each row { name, result, note, text } (the thing on the original, what it becomes, and a sentence about it), or { name, before, after, text } for a total that comes out different. Every row's text is what follows its name, as vault words it ( → <result>, : <before>, now <after>, or empty): show each row as its name, then its text, then its note. Show the user the report as vault gives it, section by section, and ask whether to convert; then call vault_convert_character with character.updatedAt. Vault answers 409 when the character's ruleset does not convert, the character is not a player character, it already has a linked sheet in ruleset.to that has been used (deleting that sheet makes way), or the character was saved while vault read it (OUT_OF_SYNC: preview again), 403 when the owner is at the character limit or lacks the ruleset, and 404 for an unknown character or one the user may not edit. A 500 here is a fault in vault's own content that this character's conversion ran into; trying again will not fix it, so tell the user it needs reporting.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "vault_preview_character_conversion"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesMongo `_id` of the character to convert (owned by the calling user, or any character for an admin with Admin Mode on).

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior4/5

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

Adds substantial context beyond the readOnly/idempotent annotations: it explains that vault makes every choice without asking the user, that the original is untouched, that numbers are preserved rather than rebuilt, and it enumerates 409/403/404/500 cases with their distinct meanings (including OUT_OF_SYNC requiring a re-preview). Only the 500 remediation is arguably redundant with common practice, and the return payload is spelled out at length.

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

Conciseness3/5

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

Purpose and the 'Creates nothing' caveat are front-loaded, but the remainder is one dense block that mixes intent, return shape, UI instructions, and four error codes with no separating structure. Each sentence earns its place, yet scanability suffers for a tool whose core instruction is one line long.

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?

Given an output schema exists, the return discussion is more than required, but nothing needed for correct invocation is missing: prerequisites, permission scope, downstream tool and argument, and the full failure taxonomy are all present.

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 100% for the single `id` parameter, so the baseline is 3; the description earns one above baseline by tying the id to permission scope ('their own, or any for an admin with Admin Mode on') and to the resulting 404 for un-editable characters.

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 with scope: 'Preview the version vault would make, in the ruleset that succeeds its own, of a character the user may edit.' The 'Creates nothing' clause and the reference to vault_convert_character make the boundary against the sibling convert tool unambiguous.

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?

Gives explicit when-to-use and what-to-do-next: 'Show the user the report as vault gives it, section by section, and ask whether to convert; then call vault_convert_character with `character.updatedAt`.' It also names the conditions where a preview is impossible (no successor ruleset, not a player character, used linked sheet).

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources