Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Convert a character to its ruleset's successor

vault_convert_character

Make the version of a character in the ruleset that succeeds its own (the preview's ruleset.to), as its linked sheet there, owned by the original's owner (it counts against the owner's character limit unless a blank linked sheet is being filled in). The original is not changed. Call vault_preview_character_conversion first, show the user its report, and convert only when they agree: pass updatedAt from the preview's character.updatedAt. Vault makes the plan again from the stored character, so the result is what the preview forecast. The new character arrives fully rested, keeps the original's gear, numbers, settings, and notes, and carries the conversion's report as a note. Returns the new character document with _conversionReport, the same shape as the preview's report: what was converted, the choices vault made, what is not in the newer ruleset and was kept, what was carried as is, what was left behind, what was not added, the totals that come out different, and anything that failed (a campaign seat that could not be made; the character still exists). Show the user that report as vault gives it, each row as its name, then its text, then its note; do not compose one. Vault answers 409 when the character changed since the preview (preview again) or already has a used linked sheet in that ruleset, 403 for the character limit or the ruleset, and 404 for an unknown character or one the user may not edit. A conversion that fails leaves nothing behind. 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>",
      "updatedAt": "<updatedAt>"
    },
    "name": "vault_convert_character"
  }
}

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).
updatedAtYes`character.updatedAt` exactly as the preview returned it. Vault answers 409 when the character has changed since; preview again.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior4/5

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write. The description goes well beyond that: the original is unchanged, the new character counts against the owner's character limit except when filling a blank linked sheet, the new character arrives fully rested and carries the conversion report as a note, and a failed conversion leaves nothing behind. Error semantics (409/403/404/500) are spelled out concretely.

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 is front-loaded, but the body is a dense chain of clauses and parentheticals ('owned by the original's owner (it counts against ... unless a blank linked sheet is being filled in)') that takes effort to parse. Nearly every sentence carries real information, yet the report-presentation instructions and the tail of error codes could be tightened.

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

Completeness4/5

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

An output schema exists, so the return values need not be described, yet the description still summarizes `_conversionReport` and instructs the agent to present it row by row. Combined with the approval gate and error map, an agent has what it needs to invoke and follow up, though the `_conversionReport` re-explanation duplicates the output schema.

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%, so the baseline is 3, but the description adds the reason `updatedAt` matters: it is an optimistic-concurrency token from the preview, and vault replans from the stored character so the result matches the forecast. That gives the agent a reason to pass the value rather than just a field name.

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+resource ('make the version of a character in the ruleset that succeeds its own') and pins it to the preview's `ruleset.to`, which separates it cleanly from vault_clone_character and vault_preview_character_conversion. An agent can tell what this does and what it is not without opening a 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?

Gives an explicit prerequisite and approval gate: call vault_preview_character_conversion first, show the user the report, convert only when they agree. It also routes recovery ('409 ... preview again') and tells the agent when not to retry (500 is a vault content fault).

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