holonovel

World Model Management

manage_world

Destructive

Create, update, remove, convert, or generate rooms, things, and exits in a persistent, audited world model so your game's spatial state stays accurate.

Instructions

Manage the world model — rooms, things, exits, and their spatial properties. create and update mutate in place and persist to the Novel; all mutations are audited; remove is permanent and requires re-creation; convert replaces the described subtree; generate creates rooms from installed table pools bounded by TTRPG_WORLD_GEN_MAX_ROOMS. create_exit links both directions; create_thing honors location_type only when location is set, and kind forces property defaults. There are no read-only actions here; inspect state with run_command (action: execute). Use when: creating, updating, removing, bulk-converting, or generating locations and objects. Do NOT use when: navigating the world — use run_command (action: execute); proposing objective-state transitions — use manage_causality; recording what an entity believes — use manage_belief.

Input Schema

Name	Required	Description
`to`	No	Destination room alias for room_b (create_exit).
`key`	No	Bound key thing name required to unlock or lock this thing when lockable (create_thing/update_thing).
`lit`	No	When true the thing is lit (create_thing/update_thing).
`from`	No	Source room alias for room_a (create_exit).
`kind`	No	Optional thing kind (create_thing).
`name`	No	Room/thing name (create/update/remove).
`room`	No	Source room (create_exit/remove_exit).
`seed`	No	Deterministic seed (generate).
`fixed`	No	When true the thing cannot be taken (create_thing/update_thing).
`noise`	No	Auditory cue text reported by listen (create_thing/update_thing).
`scent`	No	Olfactory cue text reported by smell (create_thing/update_thing).
`action`	Yes	World: create_room, update_room, remove_room, create_thing, update_thing, remove_thing, create_exit, remove_exit, convert, or generate. Causal: causal_propose, causal_admit, causal_reject, causal_list, causal_state, or causal_ingress.
`edible`	No	When true the thing can be eaten (create_thing/update_thing).
`locked`	No	When true the thing starts locked (create_thing/update_thing).
`room_a`	No	Source room (create_exit).
`room_b`	No	Destination room (create_exit).
`source`	No	Hybrid world-model source text (convert).
`options`	No	Generation options (generate): roles maps installed table names to room, objects, persons, or hazards pools; rooms requests a count bounded by TTRPG_WORLD_GEN_MAX_ROOMS.
`location`	No	Optional containing room or thing (create_thing/update_thing).
`lockable`	No	When true the thing can be locked (create_thing/update_thing).
`openable`	No	When true the thing can be opened (create_thing/update_thing).
`readable`	No	When true the thing can be read (create_thing/update_thing).
`wearable`	No	When true the thing can be worn (create_thing/update_thing).
`climbable`	No	When true the thing can be climbed (create_thing/update_thing).
`direction`	No	Direction (create_exit/remove_exit).
`drinkable`	No	When true the thing can be drunk (create_thing/update_thing).
`enterable`	No	When true the thing can be entered (create_thing/update_thing).
`read_text`	No	Text revealed when the thing is read (create_thing/update_thing).
`switchable`	No	When true the thing can be switched (create_thing/update_thing).
`description`	No	Optional description (create/update).
`switched_on`	No	When true the thing is switched on (create_thing/update_thing).
`transparent`	No	When true the thing is transparent (create_thing/update_thing).
`location_type`	No	Where the thing is placed (create_thing).

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.

Changed10 schema fields changedv2026.10.16Oct 25, 2026

removedInput schema / properties / causal_domain

Removed value: -{
-  "description": "location or scalar (causal_propose; default location).",
-  "enum": [
-    "location",
-    "scalar"
-  ],
-  "type": "string"
-}

removedInput schema / properties / causal_entity

Removed value: -{
-  "description": "Entity whose objective state is proposed (causal_propose).",
-  "type": "string"
-}

removedInput schema / properties / causal_expected_version

Removed value: -{
-  "description": "Optimistic version guard (causal_propose).",
-  "type": "number"
-}

removedInput schema / properties / causal_from

Removed value: -{
-  "description": "Expected prior value (causal_propose).",
-  "type": [
-    "string",
-    "number",
-    "boolean",
-    "null"
-  ]
-}

removedInput schema / properties / causal_key

Removed value: -{
-  "description": "State key within the entity (causal_propose).",
-  "type": "string"
-}

removedInput schema / properties / causal_origin_source

Removed value: -{
-  "description": "narrative, machine, or ruleset (causal_propose).",
-  "enum": [
-    "narrative",
-    "machine",
-    "ruleset"
-  ],
-  "type": "string"
-}

removedInput schema / properties / causal_proposal_id

Removed value: -{
-  "description": "Recorded proposal id (causal_admit/causal_reject).",
-  "type": "string"
-}

removedInput schema / properties / causal_scope

Removed value: -{
-  "description": "Scope coordinate (causal_propose; default the active Novel slug).",
-  "type": "string"
-}

removedInput schema / properties / causal_source_ordinal

Removed value: -{
-  "description": "Contributing event-log ordinal (causal_propose; default the latest event).",
-  "type": "number"
-}

removedInput schema / properties / causal_value

Removed value: -{
-  "description": "Proposed value (causal_propose/causal_ingress).",
-  "type": [
-    "string",
-    "number",
-    "boolean",
-    "null"
-  ]
-}

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

Changed3 schema fields changedv2026.10.13Oct 25, 2026

addedInput schema / properties / noise

Added value: +{
+  "description": "Auditory cue text reported by listen (create_thing/update_thing).",
+  "type": "string"
+}

addedInput schema / properties / options

Added value: +{
+  "description": "Generation options (generate): roles maps installed table names to room, objects, persons, or hazards pools; rooms requests a count bounded by TTRPG_WORLD_GEN_MAX_ROOMS.",
+  "properties": {
+    "roles": {
+      "properties": {
+        "hazards": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "objects": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "persons": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "room": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "rooms": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / scent

Added value: +{
+  "description": "Olfactory cue text reported by smell (create_thing/update_thing).",
+  "type": "string"
+}

Changed1 schema field changedOct 22, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "create_room",
-  "update_room",
-  "remove_room",
-  "create_thing",
-  "update_thing",
-  "remove_thing",
-  "create_exit",
-  "remove_exit",
-  "convert",
-  "generate",
-  "causal_propose",
-  "causal_admit",
-  "causal_reject",
-  "causal_list",
-  "causal_state",
-  "causal_ingress"
-]New value: +[
+  "create_room",
+  "update_room",
+  "remove_room",
+  "create_thing",
+  "update_thing",
+  "remove_thing",
+  "create_exit",
+  "remove_exit",
+  "convert",
+  "generate"
+]

Changed12 schema fields changedv1.0.5Oct 12, 2026

changedInput schema / properties / action / description

Previous value: -"create_room, update_room, remove_room, create_thing, update_thing, remove_thing, create_exit, remove_exit, convert, or generate."New value: +"World: create_room, update_room, remove_room, create_thing, update_thing, remove_thing, create_exit, remove_exit, convert, or generate. Causal: causal_propose, causal_admit, causal_reject, causal_list, causal_state, or causal_ingress."

changedInput schema / properties / action / enum

Previous value: -[
-  "create_room",
-  "update_room",
-  "remove_room",
-  "create_thing",
-  "update_thing",
-  "remove_thing",
-  "create_exit",
-  "remove_exit",
-  "convert",
-  "generate"
-]New value: +[
+  "create_room",
+  "update_room",
+  "remove_room",
+  "create_thing",
+  "update_thing",
+  "remove_thing",
+  "create_exit",
+  "remove_exit",
+  "convert",
+  "generate",
+  "causal_propose",
+  "causal_admit",
+  "causal_reject",
+  "causal_list",
+  "causal_state",
+  "causal_ingress"
+]

addedInput schema / properties / causal_domain

Added value: +{
+  "description": "location or scalar (causal_propose; default location).",
+  "enum": [
+    "location",
+    "scalar"
+  ],
+  "type": "string"
+}

addedInput schema / properties / causal_entity

Added value: +{
+  "description": "Entity whose objective state is proposed (causal_propose).",
+  "type": "string"
+}

addedInput schema / properties / causal_expected_version

Added value: +{
+  "description": "Optimistic version guard (causal_propose).",
+  "type": "number"
+}

addedInput schema / properties / causal_from

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Expected prior value (causal_propose)."
+}

addedInput schema / properties / causal_key

Added value: +{
+  "description": "State key within the entity (causal_propose).",
+  "type": "string"
+}

addedInput schema / properties / causal_origin_source

Added value: +{
+  "description": "narrative, machine, or ruleset (causal_propose).",
+  "enum": [
+    "narrative",
+    "machine",
+    "ruleset"
+  ],
+  "type": "string"
+}

addedInput schema / properties / causal_proposal_id

Added value: +{
+  "description": "Recorded proposal id (causal_admit/causal_reject).",
+  "type": "string"
+}

addedInput schema / properties / causal_scope

Added value: +{
+  "description": "Scope coordinate (causal_propose; default the active Novel slug).",
+  "type": "string"
+}

addedInput schema / properties / causal_source_ordinal

Added value: +{
+  "description": "Contributing event-log ordinal (causal_propose; default the latest event).",
+  "type": "number"
+}

addedInput schema / properties / causal_value

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "number"
+    },
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Proposed value (causal_propose/causal_ingress)."
+}

Changed3 schema fields changedv1.0.4Sep 30, 2026

addedInput schema / properties / from

Added value: +{
+  "description": "Source room alias for room_a (create_exit).",
+  "type": "string"
+}

addedInput schema / properties / key

Added value: +{
+  "description": "Bound key thing name required to unlock or lock this thing when lockable (create_thing/update_thing).",
+  "type": "string"
+}

addedInput schema / properties / to

Added value: +{
+  "description": "Destination room alias for room_b (create_exit).",
+  "type": "string"
+}

Addedv1.0.3Sep 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: mutations are audited and persisted, remove requires re-creation, convert replaces the described subtree, generate is bounded by TTRPG_WORLD_GEN_MAX_ROOMS, create_exit links both directions, and create_thing honors location_type only when location is set. These are non-obvious behavioral traits beyond the annotation flags.

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?

Front-loaded with purpose, then behavior, then routing. Dense but every clause carries decision-relevant information (audit, permanence, env bound, conditional param rules). Semicolon-separated clauses make it slightly harder to scan than ideal, but the length is justified by 10 sub-actions and 33 parameters.

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?

Output schema exists and annotations cover the safety profile, so the description does not need to explain return values. Combined with 100% schema coverage and the explicit use/when-not routing, an agent has everything needed to pick this tool and the correct action.

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 baseline is 3. The description adds cross-parameter semantics the schema does not: location_type is only honored when location is provided, and kind forces property defaults. It does not clarify most of the 33 parameters, but it adds real conditional meaning for a few high-value ones.

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?

Explicit verb-plus-resource: 'Manage the world model — rooms, things, exits', and it enumerates the semantics of each sub-action (create/update mutate in place, remove is permanent, convert replaces subtree, generate pulls from table pools). It also names the exact sibling tools it is not (run_command, manage_causality, manage_belief), so an agent can distinguish it without opening schemas.

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?

Contains explicit 'Use when:' and 'Do NOT use when:' blocks with alternatives for each exclusion. Navigation goes to run_command (action: execute), objective-state transitions to manage_causality, entity beliefs to manage_belief. This is the strongest kind of routing guidance.

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