Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Add an extra skill to a World

imagine_add_world_skill

Add an extra skill to a World for one ruleset. A Character of that ruleset gets it as a skill row with this ability and description and no proficiency when it joins the World, is built with the World chosen, or levels up while in the World; adding the skill writes to no Character now. Returns 201 { houseSkill: { _id, ruleset, name, attribute, description } }; 409 when the World already has a skill of that name in the ruleset. Only the World's owner, a contributor, or an admin with Admin Mode on may do this.

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>",
      "name": "<name>"
    },
    "name": "imagine_add_world_skill"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesMongo `_id` of the World.
nameYesSkill name. Used once per ruleset in a World: the app answers 409 for a name the World already has in that ruleset.
rulesetNoRuleset code the skill belongs to, from list_rulesets (one this account can use; the app answers 400 otherwise). Only Characters of this ruleset get the skill.
attributeNoThe ability the skill is rolled with, written the way a Character's skill rows of that ruleset write it in `skills[].attribute` (read one with vault_get_character).
descriptionNoWhat the skill covers. Becomes the description of the skill row a Character gets.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the annotations (non-read-only, non-idempotent, non-destructive), the description discloses that no Character is mutated at call time, the success payload shape (201 with houseSkill fields), the 409 duplicate-name case, and the required authorization level. The 409-on-duplicate behavior is directly consistent with idempotentHint=false, and the deferred-effect note is information an agent cannot get from annotations.

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?

A single dense sentence front-loads the core action, then layers effect timing, return shape, error case, and permissions in a logical order with no filler. It is on the long side and reads as a run-on, but every clause carries operational information.

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 5-parameter mutation with a full output schema and annotations, the description covers effect semantics, deferred write behavior, success response, conflict error, and authorization. Nothing an agent needs in order to call it correctly or interpret the result 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%, so the baseline is 3, but the description adds meaning: it explains that `attribute` and `description` become the ability and description of the skill row a Character later receives, and that the skill is added with no proficiency. That causal framing goes beyond the per-field schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Add an extra skill to a World for one ruleset" gives a specific verb (add), resource (world skill), and scope (single ruleset), which is enough to distinguish it from removal/update siblings by name alone. It stops short of explicitly contrasting itself with imagine_update_world_skill or imagine_add_world_house_rule.

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

Usage Guidelines3/5

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

The description explains the downstream effect precisely: the skill is granted when a Character joins, is built with the World, or levels up, and nothing is written now. It also states the permission gate (owner/contributor/Admin Mode). However, it never says when to prefer this over update_world_skill or the house-rule sibling, so routing must be inferred from the tool name.

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