Skip to main content
Glama
Sign In

Embers: Tabletop RPG Toolkit

by com.embersds
OverviewDiscussionsAdmin

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

NameRequiredDescriptionDefault
characterIdYes`_id` of the character to level (owned by the calling user, or any character for an admin with Admin Mode on).
classRuleIdNoOmit 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).
subclassRuleIdNoWith 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

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / characterId / description
      Previous value: -"`_id` of the character to level (must belong to the calling user)."New value: +"`_id` of the character to level (owned by the calling user, or any character for an admin with Admin Mode on)."
  2. Changed1 schema field changed
    • 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)."
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare the read-only/idempotent safety profile; the description adds substantial context beyond that — mode-dependent behavior, the error the vault returns when the ruleset lacks guided level-up, prerequisite-filtered pools, warn-only warnings, DELTA semantics for growth counts, and null handling for spellSlots.

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 wall of parenthetical prose that heavily overlaps the already-detailed schema descriptions. It is information-dense yet verbose and repeats structured content, so it is appropriately sized but not tight.

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?

An output schema exists, so return values need not be explained, and the description nonetheless covers the mode branches, cross-tool workflow, and edge cases. For a complex three-mode tool it is complete enough for an agent to call it correctly.

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 are themselves detailed, so the baseline is 3; the description adds mode-selection meaning (omit vs. supply classRuleId, and subclassRuleId as a tentative preview whose pick still travels via vault_level_up_pc). Much of this duplicates the schema, but the front-loaded mode disambiguation adds real value over the schema alone.

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?

Names a specific verb+resource (read the level-up plan for a character) and then disambiguates three distinct modes — CHOOSER, RECORD, and TARGET PLAN — based on parameters. An agent can tell exactly what it will get and how it differs from vault_level_up_pc and vault_record_pc_classes.

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 states when to use it ('Read this before vault_level_up_pc and key every pick off what it returns') and names the prerequisite alternative ('record the existing classes with vault_record_pc_classes first, then re-read'). It also notes that the target plan and vault_level_up_pc reject a class-less character, giving clear when-not guidance.

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 toolsInspect
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