Skip to main content
Glama

Causality Management

manage_causality
Destructive

Propose, admit, reject, list, or inspect objective causal transitions and admit external events with audited ledger records and optimistic concurrency guards.

Instructions

Manage objective causal state and transition proposals. causal_propose records a proposal without applying it; causal_admit applies the proposal and causal_reject marks it rejected without deleting the ledger record; causal_expected_version guards optimistic concurrency and causal_from records the expected prior value; causal_ingress admits an external event without a proposal. Proposals persist and are audited, and the ledger is capped by TTRPG_CAUSAL_MAX_LEDGER_ENTRIES; list and state are read-only. Causal changes are not undoable via manage_history. Use when: proposing, admitting, rejecting, listing, or inspecting causal transitions, or ingressing an external event. Do NOT use when: changing rooms, things, or exits — use manage_world.

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": {
      "action": "<action>"
    },
    "name": "manage_causality"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYescausal_propose, causal_admit, causal_reject, causal_list, causal_state, causal_ingress.
causal_keyNoState key within the entity (causal_propose).
causal_fromNoExpected prior value (causal_propose).
causal_scopeNoScope coordinate (causal_propose; default the active Novel slug).
causal_valueNoProposed value (causal_propose/causal_ingress).
causal_domainNolocation or scalar (causal_propose; default location).
causal_entityNoEntity whose objective state is proposed (causal_propose).
causal_proposal_idNoRecorded proposal id (causal_admit/causal_reject).
causal_origin_sourceNonarrative, machine, or ruleset (causal_propose).
causal_source_ordinalNoContributing event-log ordinal (causal_propose; default the latest event).
causal_expected_versionNoOptimistic version guard (causal_propose).

Output Schema

NameRequiredDescriptionDefault
textNoHuman-readable text envelope mirroring the structured result (REQ-001, REQ-548a).
statusYesMachine-readable result status: OK, NEED_INPUT, WARNING, PARTIAL, or an error category (REQ-002, REQ-548c).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2026.10.15
    • removedInput schema / properties / causal_from / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / causal_from / type
      Added value: +[
      +  "string",
      +  "number",
      +  "boolean",
      +  "null"
      +]
    • removedInput schema / properties / causal_value / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / causal_value / type
      Added value: +[
      +  "string",
      +  "number",
      +  "boolean",
      +  "null"
      +]
  2. Changed29 schema fields changedv2026.10.13
    • removedInput schema / properties / climbable
      Removed value: -{
      -  "description": "When true the thing can be climbed (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / description
      Removed value: -{
      -  "description": "Optional description (create/update).",
      -  "type": "string"
      -}
    • removedInput schema / properties / direction
      Removed value: -{
      -  "description": "Direction (create_exit/remove_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / drinkable
      Removed value: -{
      -  "description": "When true the thing can be drunk (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / edible
      Removed value: -{
      -  "description": "When true the thing can be eaten (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / enterable
      Removed value: -{
      -  "description": "When true the thing can be entered (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / fixed
      Removed value: -{
      -  "description": "When true the thing cannot be taken (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / from
      Removed value: -{
      -  "description": "Source room alias for room_a (create_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / key
      Removed value: -{
      -  "description": "Bound key thing name required to unlock or lock this thing when lockable (create_thing/update_thing).",
      -  "type": "string"
      -}
    • removedInput schema / properties / kind
      Removed value: -{
      -  "description": "Optional thing kind (create_thing).",
      -  "type": "string"
      -}
    • removedInput schema / properties / lit
      Removed value: -{
      -  "description": "When true the thing is lit (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / location
      Removed value: -{
      -  "description": "Optional containing room or thing (create_thing/update_thing).",
      -  "type": "string"
      -}
    • removedInput schema / properties / location_type
      Removed value: -{
      -  "description": "Where the thing is placed (create_thing).",
      -  "enum": [
      -    "room",
      -    "container",
      -    "supporter"
      -  ],
      -  "type": "string"
      -}
    • removedInput schema / properties / lockable
      Removed value: -{
      -  "description": "When true the thing can be locked (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / locked
      Removed value: -{
      -  "description": "When true the thing starts locked (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / name
      Removed value: -{
      -  "description": "Room/thing name (create/update/remove).",
      -  "type": "string"
      -}
    • removedInput schema / properties / openable
      Removed value: -{
      -  "description": "When true the thing can be opened (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / read_text
      Removed value: -{
      -  "description": "Text revealed when the thing is read (create_thing/update_thing).",
      -  "type": "string"
      -}
    • removedInput schema / properties / readable
      Removed value: -{
      -  "description": "When true the thing can be read (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / room
      Removed value: -{
      -  "description": "Source room (create_exit/remove_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / room_a
      Removed value: -{
      -  "description": "Source room (create_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / room_b
      Removed value: -{
      -  "description": "Destination room (create_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / seed
      Removed value: -{
      -  "description": "Deterministic seed (generate).",
      -  "type": "string"
      -}
    • removedInput schema / properties / source
      Removed value: -{
      -  "description": "Hybrid world-model source text (convert).",
      -  "type": "string"
      -}
    • removedInput schema / properties / switchable
      Removed value: -{
      -  "description": "When true the thing can be switched (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / switched_on
      Removed value: -{
      -  "description": "When true the thing is switched on (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / to
      Removed value: -{
      -  "description": "Destination room alias for room_b (create_exit).",
      -  "type": "string"
      -}
    • removedInput schema / properties / transparent
      Removed value: -{
      -  "description": "When true the thing is transparent (create_thing/update_thing).",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / wearable
      Removed value: -{
      -  "description": "When true the thing can be worn (create_thing/update_thing).",
      -  "type": "boolean"
      -}
  3. Added

TDQS

A4.5/5.0
Behavior4/5

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

Beyond the annotations it discloses traits the agent could not otherwise know: proposals persist and are audited, the ledger is capped by TTRPG_CAUSAL_MAX_LEDGER_ENTRIES, list and state are read-only, and causal changes are not undoable via manage_history. The main omission is what happens when causal_expected_version fails optimistic concurrency — the description says it 'guards' but not the resulting behavior on mismatch.

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?

The structure is strong: action semantics first, then durability/concurrency constraints, then explicit use and do-not-use blocks. There is minor redundancy where the 'Use when' list re-enumerates action names already defined in the first two sentences, but nothing is padded or vague.

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?

For an 11-parameter tool with an output schema and non-trivial annotations, the description covers action routing, durability, ledger cap, irreversibility, and sibling exclusion — enough to call it correctly. Remaining gaps are edge-case behaviors (version-conflict failure mode, what admit returns) that are lower stakes given the 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 already 100%, so the baseline is 3; the description earns a bump by explaining parameter interplay rather than restating the schema — causal_from is the expected prior value and causal_expected_version is the optimistic concurrency guard, and both belong to the propose path. It still leaves the defaults and allowed values of causal_domain, causal_origin_source, and causal_scope to the schema.

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?

The description names the specific resource (objective causal state and transition proposals) and enumerates each of the six actions with its distinct semantics — propose records without applying, admit applies, reject marks rejected without deleting, ingress admits an external event, list/state are read-only. It also explicitly contrasts with manage_world, so an agent can route between the two without opening either 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?

It gives an explicit 'Use when' list covering proposing, admitting, rejecting, listing, inspecting, and ingressing, plus a 'Do NOT use when' clause that names the correct alternative (manage_world) for room/thing/exit changes. Both the positive and negative conditions are spelled out rather than inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.