holonovel

Causality Management

manage_causality

Destructive

Propose, admit, reject, list, or inspect objective causal state transitions, and ingress external events while enforcing optimistic concurrency and auditing proposals.

Instructions

Manage objective causal state and transition proposals. causal_propose records a proposal without applying it; causal_admit applies the proposal and causal_reject discards it; 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; list and state are read-only. 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. Revert with manage_history (action: undo).

Input Schema

Name	Required	Description
`action`	Yes	causal_propose, causal_admit, causal_reject, causal_list, causal_state, causal_ingress.
`causal_key`	No	State key within the entity (causal_propose).
`causal_from`	No	Expected prior value (causal_propose).
`causal_scope`	No	Scope coordinate (causal_propose; default the active Novel slug).
`causal_value`	No	Proposed value (causal_propose/causal_ingress).
`causal_domain`	No	location or scalar (causal_propose; default location).
`causal_entity`	No	Entity whose objective state is proposed (causal_propose).
`causal_proposal_id`	No	Recorded proposal id (causal_admit/causal_reject).
`causal_origin_source`	No	narrative, machine, or ruleset (causal_propose).
`causal_source_ordinal`	No	Contributing event-log ordinal (causal_propose; default the latest event).
`causal_expected_version`	No	Optimistic version guard (causal_propose).

Output Schema

Name	Required	Description	Default
`text`	No	Human-readable text envelope mirroring the structured result (REQ-001, REQ-548a).
`status`	Yes	Machine-readable result status: OK, NEED_INPUT, WARNING, PARTIAL, or an error category (REQ-002, REQ-548c).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2026.10.15Oct 25, 2026

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"
+]

Changed29 schema fields changedv2026.10.13Oct 25, 2026

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"
-}

AddedOct 22, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds important context: proposals persist and are audited, causal_propose records without applying, causal_admit applies, causal_reject discards, and list/state are read-only. It stops short of describing audit retention or rejection consequences in depth, but the key behavioral traits are disclosed.

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 description is dense but front-loaded: purpose, action semantics, usage conditions, exclusions, and revert path all appear in sequence. It is slightly run-on with multiple clauses packed into single sentences, but every sentence carries actionable 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?

Given 11 parameters, an output schema, and annotations covering safety, the description fills the remaining gaps: action semantics, proposal lifecycle, optimistic concurrency, read-only operations, sibling exclusions, and revert guidance. An agent has enough to select and invoke the tool 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%, so the baseline is 3, but the description adds role-level meaning beyond field descriptions: causal_expected_version guards optimistic concurrency, causal_from records the expected prior value, and causal_ingress admits an external event without a proposal. This helps an agent understand how parameters relate to the action workflow.

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 opens with a specific verb+resource ('Manage objective causal state and transition proposals') and then enumerates every action and its effect. An agent can distinguish this tool from manage_world and manage_history without consulting the 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 explicitly names when to use ('proposing, admitting, rejecting, listing, or inspecting causal transitions, or ingressing an external event') and when not to use ('changing rooms, things, or exits — use manage_world'), and it routes reverts to manage_history with the exact action. Nothing is left to inference.

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