Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Search vault spells

vault_search_spells
Read-onlyIdempotent

Search the spell library the user has access to (stock spells plus their own house spells). Use this to locate a spell or power by name, ruleset, or type, or to list one class's spell list (spellList plus ruleset). Defaults to a compact summary shape (identification + summary + level + school + classes + categories + publisher / source); pass detail: 'full' to receive each spell's full description inline.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

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

Input Schema

NameRequiredDescriptionDefault
nameNoMatches the spell's name or any other name it is known by (a stock spell with a generic name also answers to its rulebook name), ignoring case, apostrophe style, spaces, and hyphens. Results show the stock name. Use `^name$` for an exact match.
skipNoPagination offset; pair with `limit` to walk results.
sortNoComma-separated field list. Prefix with `-` for descending (e.g. `-updatedAt,name`).
typeNoSpell type (the ruleset's name for a spell).
limitNoPage size; defaults to 50 when omitted. Hard cap of 200.
stockNotrue = official content only; false = user-authored only; omit to include both.
detailNoResponse shape. 'summary' (default) returns identification + summary fields; 'full' returns the complete document shape (every field inline) that non-MCP clients receive by default.summary
rulesetNoRuleset code, from list_rulesets.
characterNoMongo `_id` of the vault Character you are picking content for (adding to its sheet, building or levelling it). Pass it whenever the results are offered for a particular Character: the stock records its Worlds hide are left out, as in the app's own pickers. An id that names no Character the user can see is ignored.
spellListNoA class name (e.g. `Wizard`): only the spells on that class's spell list. Requires `ruleset`.

Output Schema

NameRequiredDescriptionDefault
resultsNo
paginationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / character
      Added value: +{
      +  "description": "Mongo `_id` of the vault Character you are picking content for (adding to its sheet, building or levelling it). Pass it whenever the results are offered for a particular Character: the stock records its Worlds hide are left out, as in the app's own pickers. An id that names no Character the user can see is ignored.",
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / name / description
      Previous value: -"Substring match on spell name (case-insensitive). Use `^name$` for an exact match."New value: +"Matches the spell's name or any other name it is known by (a stock spell with a generic name also answers to its rulebook name), ignoring case, apostrophe style, spaces, and hyphens. Results show the stock name. Use `^name$` for an exact match."
  3. Changed1 schema field changed
    • addedInput schema / properties / spellList
      Added value: +{
      +  "description": "A class name (e.g. `Wizard`): only the spells on that class's spell list. Requires `ruleset`.",
      +  "type": "string"
      +}
  4. Changed2 schema fields changed
    • changedInput schema / properties / ruleset / description
      Previous value: -"Ruleset code (e.g. '5th Edition', '5e24', 'PFRPG', 'Savage Worlds', 'Universal')."New value: +"Ruleset code, from list_rulesets."
    • changedInput schema / properties / type / description
      Previous value: -"Spell type. 5e / 5e24 use 'Spell'; Savage Worlds uses 'Power'."New value: +"Spell type (the ruleset's name for a spell)."
  5. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is lighter. It adds real behavioral context by disclosing that results default to a compact summary shape and that detail: 'full' yields full descriptions inline — a response-shape characteristic the annotations do not express. It omits pagination/limit behavior, but the schema covers that.

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

Conciseness5/5

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

Two sentences, front-loaded with the resource and scope, then the search modes, then the response-shape default. Every clause carries information; nothing is filler.

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 and the annotations cover safety, so the description doesn't need to explain return values. It covers the primary search modes and the detail knob for a 10-parameter tool, leaving pagination, sorting, and the character-scoping behavior to the schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both the detail modes and the spellList/ruleset dependency are already documented in the schema. The description restates those interactions in prose, which aids scanning but adds little semantic meaning beyond the structured fields. Baseline 3 is appropriate when the schema carries the weight.

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 ('Search the spell library') plus its scope (stock spells plus the user's own house spells), and enumerates the search modes: by name, ruleset, type, or one class's spell list. An agent can distinguish this from vault_get_spell or vault_search_items without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this to locate a spell or power by name, ruleset, or type, or to list one class's spell list' gives clear triggering contexts for each mode. It stops short of explicitly naming the retrieval alternative (vault_get_spell) or stating when not to use it, so no exclusions or alternatives are offered.

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