Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Level up a player character

vault_level_up_pc

Advance a character one level in a class, in one call, from a flat draft of choices, for a ruleset with guided level-up (vault answers an error naming the ruleset otherwise). A class-less character (no Class entries) is rejected — record its existing classes with vault_record_pc_classes first. Vault validates every pick against the plan's pools (prerequisites enforced; grown choices demand only their delta counts) and mutates the character: the class entry's stored level bumps (or a new class entry lands with the class's multiclassGrants), the level's features snapshot onto the sheet (a subclass picked through the class's subclass-choice ability lands as its own entry and cascades its features), ability-score increases bake, HP and hit dice grow per the hitPoints choice, use-counters resize (spent uses stay spent), the combined multiclass spell-slot pool reconciles, core.class updates to " , ...", XP floors at the new level's minimum (or your exact xp), and a level-up note records the choices; the engine applies every rule behind those changes. Read vault_get_levelup_options first — required: characterId, classRuleId, hitPoints. Supply abilityChoices for every feature choice the plan surfaced (including the subclass pick and grown choice lists), the sub-pick maps for anything the picked options themselves carry (a Feat picked at an Ability Score Improvement level may carry its own choice and abilities, whose picks go in the same maps), spellSwapPicks for the optional known-spell swaps the plan offers, multiclassSkillProficiencies/multiclassToolProficiencies when entering a class, and optional exact xp. The updated character and a summary of what changed are returned. On an invalid draft vault returns the specific reason as a tool error — fix the draft and retry; if a surfaced pick genuinely cannot be satisfied, allowIncomplete: true applies the level and skips the shortfall instead.

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": {
      "characterId": "<characterId>",
      "classRuleId": "<classRuleId>",
      "hitPoints": "<hitPoints>"
    },
    "name": "vault_level_up_pc"
  }
}

Input Schema

NameRequiredDescriptionDefault
xpNoThe character's total XP after this level-up, for tables tracking exact XP. Must be >= the plan's `xp.minimumForNewTotal`; omit to let vault floor the stored XP at that minimum.
hitPointsYesHow the level's hit points are gained: `method` is one of the schema's methods (the plan's `hitPoints` fields carry what each one uses); `value` is a die the PLAYER rolled, for a method that takes one.
characterIdYes`_id` of the character to level (owned by the calling user, or any character for an admin with Admin Mode on).
classRuleIdYesRequired. The base Class rule to advance one level — a held class entry (its stored level bumps) or a class the character doesn't hold yet (multiclass: a new class entry is stamped). From the chooser's `classEntries[].classRuleId` / `multiclassOptions[]._id`.
abilityChoicesNoruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (the class's subclass-choice ability — value = the picked subclass `_id`; a choice among feats — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`; a Feat picked at an Ability Score Improvement level may carry its own `choice` and abilities, and their picks go in these same maps (the plan's option rows list them). Pools are prerequisite-filtered; an unqualified pick rejects the draft.
spellSwapPicksNoOptional spell swaps (known-spell casters whose plan offers them), keyed by the owning Spellcasting rule's `_id`: each entry `{ replace, with }` replaces one known spell with another. The plan's `growth[]` rows carry `spellSwap` (`{ count, known, options }`, each spell `{ _id, name, level, school }`) and `levelUpRules.spellSwapOptions` lists the known spells and the legal replacements per owner. A `spellSwap.schoolLimit` `{ schools, anySchoolPicks }` (a caster limited to two schools) allows a replacement outside `schools` only when, after the swap, the character knows no more spells outside them than `anySchoolPicks`; vault refuses a swap past it. Send at most the plan's count; a key whose rule swaps nothing this level is ignored.
allowIncompleteNoSanctioned partial apply: `true` lets vault accept UNDER-filled pick families — the level lands and only what was picked is granted; the shortfall is simply skipped (the player can edit the sheet later). Overfilled, duplicate, out-of-pool, and prerequisite-failing picks still reject. Use it as the escape when a surfaced pick cannot be satisfied; never as a shortcut past picks you can supply.
abilityBumpPicksNoAbility-score-increase picks for a gained rule carrying an `abilityScoreBump`: `{ option, lines }` keyed by the granting rule's `_id`, same shape as `vault_build_pc`. The engine applies whatever the increase changes elsewhere on the sheet.
spellChoicePicksNoPicks for spellChoices blocks on gained/grown rules, keyed `"<ruleId>:<blockIndex>"` (authored index — the projected array may hold nulls; count them). Grown blocks demand only the DELTA count ("learn N more spells").
preparedSpellPicksNo"Prepare N more" picks for rules whose preparedSpells count grew, keyed by the granting rule's `_id`. The pool is the character's UNPREPARED granted leveled spells plus any picked this level-up; send exactly the plan's surfaced count. Where a prepared count follows the casting ability modifier, the plan's `preparedSpells` row carries `countSource`, `castingAbility`, and `from`.
castingAbilityPicksNoSpellcasting-ability picks for blocks surfacing `castingAbilityOptions`, keyed like spellChoicePicks.
spellListChoicePicksNoPicks for a NEWLY gained rule's spellListChoices — `{ category, picks, castingAbility? }` keyed `"<ruleId>:<blockIndex>"`, exactly as in `vault_build_pc`.
proficiencyChoicePicksNoPicks for proficiencyChoices grants on gained/grown rules, keyed `"<ruleId>:<grantIndex>"` — same keying and rules as `vault_build_pc`. Grown grants demand only the DELTA count the plan surfaced. An EXPERTISE grant picks from the pool the rule authoring guide describes (vault_get_authoring_guide, entityType .rule., proficiencyChoices); vault rejects picks that do not fit.
multiclassToolProficienciesNoTool picks for the entered class's `multiclassGrants.toolChoices` (multiclass only): exactly `count` names from its (group-expanded) options.
multiclassSkillProficienciesNoSkill picks for the entered class's `multiclassGrants.skillChoices` (multiclass only): exactly `count` names from its options.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / abilityChoices / description
      Previous value: -"ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (the class's subclass-choice ability — value = the picked subclass `_id`; a choice among feats — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`. Pools are prerequisite-filtered; an unqualified pick rejects the draft."New value: +"ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (the class's subclass-choice ability — value = the picked subclass `_id`; a choice among feats — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`; a Feat picked at an Ability Score Improvement level may carry its own `choice` and abilities, and their picks go in these same maps (the plan's option rows list them). Pools are prerequisite-filtered; an unqualified pick rejects the draft."
    • changedInput schema / properties / preparedSpellPicks / description
      Previous value: -"\"Prepare N more\" picks for rules whose preparedSpells count grew, keyed by the granting rule's `_id`. The pool is the character's UNPREPARED granted leveled spells plus any picked this level-up; send exactly the plan's surfaced count."New value: +"\"Prepare N more\" picks for rules whose preparedSpells count grew, keyed by the granting rule's `_id`. The pool is the character's UNPREPARED granted leveled spells plus any picked this level-up; send exactly the plan's surfaced count. Where a prepared count follows the casting ability modifier, the plan's `preparedSpells` row carries `countSource`, `castingAbility`, and `from`."
    • addedInput schema / properties / spellSwapPicks
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "replace": {
      +          "description": "Mongo `_id` reference (24-character hex string).",
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "with": {
      +          "description": "Mongo `_id` reference (24-character hex string).",
      +          "minLength": 1,
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "replace",
      +        "with"
      +      ],
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "description": "Optional spell swaps (known-spell casters whose plan offers them), keyed by the owning Spellcasting rule's `_id`: each entry `{ replace, with }` replaces one known spell with another. The plan's `growth[]` rows carry `spellSwap` (`{ count, known, options }`, each spell `{ _id, name, level, school }`) and `levelUpRules.spellSwapOptions` lists the known spells and the legal replacements per owner. A `spellSwap.schoolLimit` `{ schools, anySchoolPicks }` (a caster limited to two schools) allows a replacement outside `schools` only when, after the swap, the character knows no more spells outside them than `anySchoolPicks`; vault refuses a swap past it. Send at most the plan's count; a key whose rule swaps nothing this level is ignored.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
  2. 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)."
  3. Changed6 schema fields changed
    • changedInput schema / properties / abilityBumpPicks / description
      Previous value: -"Ability-score-increase picks for a gained rule carrying an `abilityScoreBump` (the ASI feat picked at level 4+): `{ option, lines }` keyed by the granting rule's `_id`, same shape as `vault_build_pc`. A Constitution increase raises HP retroactively for every level already held."New value: +"Ability-score-increase picks for a gained rule carrying an `abilityScoreBump`: `{ option, lines }` keyed by the granting rule's `_id`, same shape as `vault_build_pc`. The engine applies whatever the increase changes elsewhere on the sheet."
    • changedInput schema / properties / abilityChoices / description
      Previous value: -"ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (a Fighting Style; the class's subclass-choice ability at level 3 — value = the picked subclass `_id`; an ASI ability — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries, e.g. new invocations — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`. Pools are prerequisite-filtered; an unqualified pick rejects the draft."New value: +"ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (the class's subclass-choice ability — value = the picked subclass `_id`; a choice among feats — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`. Pools are prerequisite-filtered; an unqualified pick rejects the draft."
    • changedInput schema / properties / classRuleId / description
      Previous value: -"Required. The base Class rule to advance one level — a held class entry (its stored level bumps) or a class the character doesn't hold yet (multiclass: a second class entry is stamped at level 1). From the chooser's `classEntries[].classRuleId` / `multiclassOptions[]._id`."New value: +"Required. The base Class rule to advance one level — a held class entry (its stored level bumps) or a class the character doesn't hold yet (multiclass: a new class entry is stamped). From the chooser's `classEntries[].classRuleId` / `multiclassOptions[]._id`."
    • changedInput schema / properties / hitPoints / description
      Previous value: -"How the level's hit points are gained: `{method:'average'}` takes the fixed average (the plan's `hitPoints.average`); `{method:'roll', value}` records a die the PLAYER rolled — value must be 1..the class's hit die. The Constitution modifier is added server-side either way."New value: +"How the level's hit points are gained: `method` is one of the schema's methods (the plan's `hitPoints` fields carry what each one uses); `value` is a die the PLAYER rolled, for a method that takes one."
    • changedInput schema / properties / proficiencyChoicePicks / description
      Previous value: -"Picks for proficiencyChoices grants on gained/grown rules, keyed `\"<ruleId>:<grantIndex>\"` — same keying and rules as `vault_build_pc`. Grown grants demand only the DELTA count the plan surfaced. An EXPERTISE grant's pool is the character's proficient skills MINUS those that already carry Expertise (narrowed to the grant's own options for mode 'specific'); when that pool is at/below the count, vault auto-grants and expects NO picks."New value: +"Picks for proficiencyChoices grants on gained/grown rules, keyed `\"<ruleId>:<grantIndex>\"` — same keying and rules as `vault_build_pc`. Grown grants demand only the DELTA count the plan surfaced. An EXPERTISE grant picks from the pool the rule authoring guide describes (vault_get_authoring_guide, entityType .rule., proficiencyChoices); vault rejects picks that do not fit."
    • changedInput schema / properties / spellListChoicePicks / description
      Previous value: -"Picks for a NEWLY gained rule's spellListChoices (the Magic Initiate shape) — `{ category, picks, castingAbility? }` keyed `\"<ruleId>:<blockIndex>\"`, exactly as in `vault_build_pc`."New value: +"Picks for a NEWLY gained rule's spellListChoices — `{ category, picks, castingAbility? }` keyed `\"<ruleId>:<blockIndex>\"`, exactly as in `vault_build_pc`."
  4. Changed17 schema fields changed
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +{}
    • addedInput schema / properties / abilityBumpPicks
      Added value: +{
      +  "additionalProperties": {
      +    "additionalProperties": {},
      +    "properties": {
      +      "lines": {
      +        "items": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "type": "array"
      +      },
      +      "option": {
      +        "maximum": 9007199254740991,
      +        "minimum": 0,
      +        "type": "integer"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "description": "Ability-score-increase picks for a gained rule carrying an `abilityScoreBump` (the ASI feat picked at level 4+): `{ option, lines }` keyed by the granting rule's `_id`, same shape as `vault_build_pc`. A Constitution increase raises HP retroactively for every level already held.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / abilityChoices
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "description": "ruleChoice picks, keyed by the OWNING rule's `_id`: a gained feature's choice (a Fighting Style; the class's subclass-choice ability at level 3 — value = the picked subclass `_id`; an ASI ability — value = the picked feat `_id`) AND a grown held rule's choice (`growth[]` entries, e.g. new invocations — supply the NEW picks only, the delta count). A picked option's own sub-choices (a feat's skill picks, its abilityScoreBump) go in the other maps keyed by the picked option's `_id`, exactly as in `vault_build_pc`. Pools are prerequisite-filtered; an unqualified pick rejects the draft.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / allowIncomplete
      Added value: +{
      +  "description": "Sanctioned partial apply: `true` lets vault accept UNDER-filled pick families — the level lands and only what was picked is granted; the shortfall is simply skipped (the player can edit the sheet later). Overfilled, duplicate, out-of-pool, and prerequisite-failing picks still reject. Use it as the escape when a surfaced pick cannot be satisfied; never as a shortcut past picks you can supply.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / castingAbilityPicks
      Added value: +{
      +  "additionalProperties": {
      +    "enum": [
      +      "strength",
      +      "dexterity",
      +      "constitution",
      +      "intelligence",
      +      "wisdom",
      +      "charisma"
      +    ],
      +    "type": "string"
      +  },
      +  "description": "Spellcasting-ability picks for blocks surfacing `castingAbilityOptions`, keyed like spellChoicePicks.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / characterId
      Added value: +{
      +  "description": "`_id` of the character to level (must belong to the calling user).",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / classRuleId
      Added value: +{
      +  "description": "Required. The base Class rule to advance one level — a held class entry (its stored level bumps) or a class the character doesn't hold yet (multiclass: a second class entry is stamped at level 1). From the chooser's `classEntries[].classRuleId` / `multiclassOptions[]._id`.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / hitPoints
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "How the level's hit points are gained: `{method:'average'}` takes the fixed average (the plan's `hitPoints.average`); `{method:'roll', value}` records a die the PLAYER rolled — value must be 1..the class's hit die. The Constitution modifier is added server-side either way.",
      +  "properties": {
      +    "method": {
      +      "enum": [
      +        "average",
      +        "roll"
      +      ],
      +      "type": "string"
      +    },
      +    "value": {
      +      "exclusiveMinimum": 0,
      +      "maximum": 9007199254740991,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "method"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / multiclassSkillProficiencies
      Added value: +{
      +  "description": "Skill picks for the entered class's `multiclassGrants.skillChoices` (multiclass only): exactly `count` names from its options.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / multiclassToolProficiencies
      Added value: +{
      +  "description": "Tool picks for the entered class's `multiclassGrants.toolChoices` (multiclass only): exactly `count` names from its (group-expanded) options.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / preparedSpellPicks
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "description": "Mongo `_id` reference (24-character hex string).",
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "description": "\"Prepare N more\" picks for rules whose preparedSpells count grew, keyed by the granting rule's `_id`. The pool is the character's UNPREPARED granted leveled spells plus any picked this level-up; send exactly the plan's surfaced count.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / proficiencyChoicePicks
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "description": "Picks for proficiencyChoices grants on gained/grown rules, keyed `\"<ruleId>:<grantIndex>\"` — same keying and rules as `vault_build_pc`. Grown grants demand only the DELTA count the plan surfaced. An EXPERTISE grant's pool is the character's proficient skills MINUS those that already carry Expertise (narrowed to the grant's own options for mode 'specific'); when that pool is at/below the count, vault auto-grants and expects NO picks.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / spellChoicePicks
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "description": "Mongo `_id` reference (24-character hex string).",
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "description": "Picks for spellChoices blocks on gained/grown rules, keyed `\"<ruleId>:<blockIndex>\"` (authored index — the projected array may hold nulls; count them). Grown blocks demand only the DELTA count (\"learn N more spells\").",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / spellListChoicePicks
      Added value: +{
      +  "additionalProperties": {
      +    "additionalProperties": {},
      +    "properties": {
      +      "castingAbility": {
      +        "enum": [
      +          "strength",
      +          "dexterity",
      +          "constitution",
      +          "intelligence",
      +          "wisdom",
      +          "charisma"
      +        ],
      +        "type": "string"
      +      },
      +      "category": {
      +        "type": "string"
      +      },
      +      "picks": {
      +        "additionalProperties": {
      +          "items": {
      +            "description": "Mongo `_id` reference (24-character hex string).",
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "propertyNames": {
      +          "type": "string"
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "description": "Picks for a NEWLY gained rule's spellListChoices (the Magic Initiate shape) — `{ category, picks, castingAbility? }` keyed `\"<ruleId>:<blockIndex>\"`, exactly as in `vault_build_pc`.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / xp
      Added value: +{
      +  "description": "The character's total XP after this level-up, for tables tracking exact XP. Must be >= the plan's `xp.minimumForNewTotal`; omit to let vault floor the stored XP at that minimum.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / required
      Added value: +[
      +  "characterId",
      +  "classRuleId",
      +  "hitPoints"
      +]
  5. 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 generic mutation profile (readOnly=false, destructive=false, idempotent=false); the description goes far beyond by enumerating each mutation — stored class level bump or new multiclass entry, feature snapshot with subclass cascade, ability-score baking, HP/hit-dice growth, use-counter resize with spent uses preserved, spell-slot pool reconciliation, `core.class` rewrite, XP flooring, and a level-up note. It also discloses validation behavior (pools prerequisite-filtered, overfilled/out-of-pool picks rejected) and the partial-apply semantics.

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?

Content is largely load-bearing and the purpose is front-loaded in the first clause, but the middle is a single run-on sentence chaining a dozen mutations with semicolons and commas, which is hard to scan. A short bulleted split of 'what changes' vs 'what to supply' would carry the same information far more legibly.

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 15-parameter mutation tool with nested objects, annotations, and an output schema, the description is complete: it covers sequencing, required picks per choice family, error recovery, and the partial-apply escalation. Return values are summarized ('updated character and a `summary`') and need not be expanded further since an output schema exists.

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 schema already documents every field; the description nonetheless adds selection logic the schema does not — that grown choice lists demand only the delta count, that a picked option's sub-choices key off the picked option's `_id` exactly as in `vault_build_pc`, and that `spellSwapPicks` keys whose rule swaps nothing are ignored. Only mildly redundant with the already-verbose schema descriptions, so short of a 5.

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 (advance a character one level in a class) plus the operational mode (one call, flat draft, guided ruleset). It also names the two siblings an agent must consider first — `vault_get_levelup_options` and `vault_record_pc_classes` — so it is distinguishable without opening any 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?

Explicit prerequisites: call `vault_get_levelup_options` first, and record classes via `vault_record_pc_classes` because a class-less character is rejected. It also states the escape condition (`allowIncomplete: true` only when a surfaced pick genuinely cannot be satisfied) and warns never to use it as a shortcut, plus the retry-on-tool-error loop.

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