Embers: Tabletop RPG Toolkit

Read a character's level-up plan

vault_get_levelup_options

Read-onlyIdempotent

Read the level-up plan for a character whose ruleset has guided level-up (vault answers an error naming the ruleset otherwise) — the same computation vault's web wizard renders. Without classRuleId: the CHOOSER (the character's class entries with stored levels, the multiclass candidates each with warn-only prerequisite warnings[], xp.minimumForNext, atMaxLevel). A character with NO class entries (a hand-made sheet) gets RECORD mode instead: needsClassRecord: true plus recordOptions[] (every usable base class with subclasses[] and its subclassLevel) — record the existing classes with vault_record_pc_classes first, then re-read; the target plan and vault_level_up_pc reject a class-less character. With classRuleId: the TARGET PLAN for advancing that class one level — features[] (gained at the new level) / subclassFeatures[] / growth[] (held rules whose choice counts grew; their counts are DELTAS, "pick N more") each carrying its open choice blocks in the creation-option shape, plus multiclassGrants (entering a new class: fixed proficiency lines + skill/tool pickers), hitPoints {hitDie, average, conModifier}, prerequisiteWarnings[] (multiclass entry is warn-only, the player may proceed), spellSlots (combined multiclass pool preview, null when the plan has no combined pool), and xp {current, minimumForNewTotal}. Add subclassRuleId (at a subclass level, before committing the pick) to preview that candidate's features. ruleChoice pools arrive prerequisite-FILTERED — every listed option is one the character qualifies for at the level being gained. Read this before vault_level_up_pc and key every pick off what it returns.

Input Schema

TableJSON Schema

Name	Required	Description
`characterId`	Yes	`_id` of the character to level (must belong to the calling user).
`classRuleId`	No	Omit for the CHOOSER (the character's class entries with their stored levels, the multiclass candidates with warn-only prerequisite warnings, the XP floor for the next level, atMaxLevel). Supply a base Class rule `_id` — one of the chooser's `classEntries[].classRuleId` to advance a held class, or a `multiclassOptions[]._id` to enter a new class — for the TARGET PLAN: `features[]` / `subclassFeatures[]` / `growth[]` (each feature in the creation option shape with its open choice blocks: `choice` {label,count,options}, spellChoices (each block carries `prepared` — true = its spells land always-prepared and are EXCLUDED from the preparedSpellPicks pool), spellListChoices (same `prepared` flag), preparedSpells, proficiencyChoices, abilityScoreBump; `growth[]` entries are already-held rules whose counts grew this level — their `count`s are DELTAS, "pick N more"), `multiclassGrants` (when entering a new class), `hitPoints` {hitDie, average, conModifier}, `prerequisiteWarnings[]` (warn-only), `spellSlots` (the combined multiclass pool preview, null when the plan has no combined pool), `openPickCount`, and `xp` {current, minimumForNewTotal}. ruleChoice pools arrive PREREQUISITE-FILTERED (an unqualified pick is also rejected on apply).
`subclassRuleId`	No	With classRuleId, previews a tentative subclass pick before committing: the candidate's features (and their open choices) resolve into `subclassFeatures[]`. The pick itself still travels in `vault_level_up_pc.abilityChoices`, keyed by the class's subclass-choice ability.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 27, 2026

changedInput schema / properties / classRuleId / description

Previous value: -"Omit for the CHOOSER (the character's class entries with their stored levels, the multiclass candidates with warn-only prerequisite warnings, the XP floor for the next level, atMaxLevel). Supply a base Class rule `_id` — one of the chooser's `classEntries[].classRuleId` to advance a held class, or a `multiclassOptions[]._id` to enter a new class at level 1 — for the TARGET PLAN: `features[]` / `subclassFeatures[]` / `growth[]` (each feature in the creation option shape with its open choice blocks: `choice` {label,count,options}, spellChoices (each block carries `prepared` — true = its spells land always-prepared and are EXCLUDED from the preparedSpellPicks pool), spellListChoices (same `prepared` flag), preparedSpells, proficiencyChoices, abilityScoreBump; `growth[]` entries are already-held rules whose counts grew this level — their `count`s are DELTAS, \"pick N more\"), `multiclassGrants` (when entering a new class), `hitPoints` {hitDie, average, conModifier}, `prerequisiteWarnings[]` (warn-only), `spellSlots` (the combined multiclass pool preview, null unless 2+ contributing casters), `openPickCount`, and `xp` {current, minimumForNewTotal}. ruleChoice pools arrive PREREQUISITE-FILTERED (an unqualified pick is also rejected on apply)."New value: +"Omit for the CHOOSER (the character's class entries with their stored levels, the multiclass candidates with warn-only prerequisite warnings, the XP floor for the next level, atMaxLevel). Supply a base Class rule `_id` — one of the chooser's `classEntries[].classRuleId` to advance a held class, or a `multiclassOptions[]._id` to enter a new class — for the TARGET PLAN: `features[]` / `subclassFeatures[]` / `growth[]` (each feature in the creation option shape with its open choice blocks: `choice` {label,count,options}, spellChoices (each block carries `prepared` — true = its spells land always-prepared and are EXCLUDED from the preparedSpellPicks pool), spellListChoices (same `prepared` flag), preparedSpells, proficiencyChoices, abilityScoreBump; `growth[]` entries are already-held rules whose counts grew this level — their `count`s are DELTAS, \"pick N more\"), `multiclassGrants` (when entering a new class), `hitPoints` {hitDie, average, conModifier}, `prerequisiteWarnings[]` (warn-only), `spellSlots` (the combined multiclass pool preview, null when the plan has no combined pool), `openPickCount`, and `xp` {current, minimumForNewTotal}. ruleChoice pools arrive PREREQUISITE-FILTERED (an unqualified pick is also rejected on apply)."

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 only declare a safe read (readOnlyHint, idempotentHint); the description adds substantial behavior beyond that: the error thrown for non-guided rulesets, RECORD mode fallback with needsClassRecord/recordOptions, warn-only prerequisite semantics, DELTA counts on growth[], and prerequisite-FILTERED choice pools. This is rich disclosure that structured fields do not provide.

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?

Front-loaded with the core purpose, then organized by mode (Without classRuleId / With classRuleId / subclassRuleId). It is very long and parenthetical-heavy, but nearly every clause carries actionable detail (mode keys, field semantics, cross-tool flow) rather than filler.

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?

Despite an output schema existing, the description fully equips the agent: it explains both response shapes, the fallback path, prerequisite filtering, and the downstream call sequence. Nothing needed to select or invoke the tool correctly is missing.

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% and the schema descriptions already document each parameter in depth, so the baseline is 3. The description nonetheless adds mode-selection semantics (omit classRuleId for CHOOSER, supply it for TARGET PLAN) and clarifies subclassRuleId is a pre-commit preview whose pick still travels through vault_level_up_pc, which goes beyond the schema's field-level text.

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 the specific verb and resource ('Read the level-up plan for a character whose ruleset has guided level-up') and precisely delineates the two output modes keyed on classRuleId (CHOOSER vs TARGET PLAN). It is clearly distinguishable from siblings lke vault_level_up_pc and vault_get_pc_creation_options.

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?

Explicitly says 'Read this before vault_level_up_pc and key every pick off what it returns,' names the alternative path for a class-less character ('record the existing classes with vault_record_pc_classes first, then re-read'), and notes the error case when the ruleset is wrong. When-to-use and dependencies are fully covered.

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?