holonovel

Scene Management

manage_scene

Destructive

Set the active scene's description, directive, and offered choices, and resolve oracle chance questions to frame narrative state before recording story beats.

Instructions

Manage the active scene and its narrative framing — scene description, directive, choices, and oracle rolls, distinct from the world model's rooms and things. set overwrites the scene's description and metadata and derives the description from location only when description is omitted; directive replaces the active directive; choices replaces the offered options; oracle resolves a chance question and records the roll. set and directive require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo). Use when: setting scene state, issuing a directive, offering choices, or consulting the oracle. Do NOT use when: recording a story beat — use manage_story (action: record); staging presence or autonomy — use manage_staging.

Input Schema

Name	Required	Description
`beat`	No	Story-beat tag (set): setup, escalation, turning_point, climax, resolution, denouement.
`seed`	No	Deterministic seed (oracle).
`action`	Yes	set, directive, presence, autonomy, choices, or oracle.
`prompt`	No	Choice prompt (choices).
`choices`	No	List of choices (choices).
`context`	No	Context for the choice (choices).
`location`	No	Scene location (set).
`question`	No	Question to resolve (oracle).
`directive`	No	Narrative directive (directive).
`atmosphere`	No	Atmosphere (set).
`likelihood`	No	Likelihood tier (oracle).
`scene_type`	No	Scene-type tag or array (set).
`description`	No	Scene description (set).
`time_of_day`	No	Time of day (set).
`fast_forward`	No	Narrative fast-forward (set).
`allow_freeform`	No	Allow free-form response (choices).
`adventure_scene`	No	Adventure-scene waypoint anchor; empty or null clears (set).
`skip_transition_hook`	No	Skip the scene-transition hook (set).

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.

Changed11 schema fields changedv2026.10.16Oct 25, 2026

removedInput schema / properties / after_user

Removed value: -{
-  "description": "Reset the pooled spoken-set for a new user turn (next_speaker).",
-  "type": "boolean"
-}

removedInput schema / properties / confirmation

Removed value: -{
-  "description": "Confirmation mode (autonomy).",
-  "enum": [
-    "auto",
-    "confirm",
-    "prompt"
-  ],
-  "type": "string"
-}

removedInput schema / properties / creativity

Removed value: -{
-  "description": "Creativity (autonomy).",
-  "enum": [
-    "predictable",
-    "standard",
-    "chaotic"
-  ],
-  "type": "string"
-}

removedInput schema / properties / entity_ids

Removed value: -{
-  "description": "Entities present (presence).",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedInput schema / properties / force

Removed value: -{
-  "description": "NPC forced as the next speaker (cast/next_speaker).",
-  "type": "string"
-}

removedInput schema / properties / level

Removed value: -{
-  "description": "Autonomy level (autonomy).",
-  "enum": [
-    "full",
-    "mechanical_prompt",
-    "manual"
-  ],
-  "type": "string"
-}

removedInput schema / properties / mute

Removed value: -{
-  "description": "NPC muted from speaker selection (cast).",
-  "type": "string"
-}

removedInput schema / properties / safety

Removed value: -{
-  "description": "Safety tier (autonomy).",
-  "enum": [
-    "safe",
-    "moderate",
-    "hardcore"
-  ],
-  "type": "string"
-}

removedInput schema / properties / select

Removed value: -{
-  "description": "NPC selected as the manual speaker (cast/next_speaker).",
-  "type": "string"
-}

removedInput schema / properties / strategy

Removed value: -{
-  "description": "Speaker-selection strategy (cast).",
-  "enum": [
-    "manual",
-    "natural",
-    "list",
-    "pooled"
-  ],
-  "type": "string"
-}

removedInput schema / properties / unmute

Removed value: -{
-  "description": "NPC restored to speaker selection (cast).",
-  "type": "string"
-}

Changed2 schema fields changedv2026.10.15Oct 25, 2026
- removedInput schema / properties / adventure_scene / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / adventure_scene / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedv2026.10.13Oct 25, 2026

addedInput schema / properties / after_user

Added value: +{
+  "description": "Reset the pooled spoken-set for a new user turn (next_speaker).",
+  "type": "boolean"
+}

addedInput schema / properties / force

Added value: +{
+  "description": "NPC forced as the next speaker (cast/next_speaker).",
+  "type": "string"
+}

addedInput schema / properties / mute

Added value: +{
+  "description": "NPC muted from speaker selection (cast).",
+  "type": "string"
+}

addedInput schema / properties / select

Added value: +{
+  "description": "NPC selected as the manual speaker (cast/next_speaker).",
+  "type": "string"
+}

addedInput schema / properties / strategy

Added value: +{
+  "description": "Speaker-selection strategy (cast).",
+  "enum": [
+    "manual",
+    "natural",
+    "list",
+    "pooled"
+  ],
+  "type": "string"
+}

addedInput schema / properties / unmute

Added value: +{
+  "description": "NPC restored to speaker selection (cast).",
+  "type": "string"
+}

Changed1 schema field changedOct 22, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "set",
-  "directive",
-  "presence",
-  "autonomy",
-  "choices",
-  "oracle"
-]New value: +[
+  "set",
+  "directive",
+  "choices",
+  "oracle"
+]

Changed1 schema field changedv1.0.4Sep 30, 2026

changedInput schema / properties / beat / description

Previous value: -"Story-beat tag (set)."New value: +"Story-beat tag (set): setup, escalation, turning_point, climax, resolution, denouement."

Addedv1.0.3Sep 29, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Adds substantial context beyond the annotations: set and directive require the GM or Editor badge, persist to the Novel, are audited, and are reversible via manage_history (action: undo). It also discloses that set overwrites existing description/metadata, which corroborates destructiveHint=true. It stops short of noting non-idempotency or the additive side effects of oracle rolls, so it is strong but not complete.

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?

Dense but front-loaded: the purpose leads, per-action semantics follow, then permissions, then explicit use/do-not-use routing. Every sentence carries distinct information, and the 'Use when' / 'Do NOT use when' scaffolding makes it scannable despite the length.

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 18-parameter destructive tool, it covers the four actions, the permission model, persistence/audit behavior, and undo path, and the output schema means return values need not be described. The gap is fast_forward and its nested changes/skip_countdowns semantics, which an agent must infer entirely from the schema.

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 a genuine rule not in the schema: description is derived from location only when description is omitted. It also maps parameters to actions (directive replaces the active directive, choices replaces the offered options). The notable omission is fast_forward, a nested object controlling time skips and NPC changes, which is never explained.

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?

Names a specific verb+resource ('Manage the active scene and its narrative framing') and enumerates the four sub-operations it covers: description, directive, choices, and oracle rolls. It explicitly separates the tool from the world model's 'rooms and things' and from the staging siblings, so an agent can discriminate it without opening 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?

Provides an explicit 'Use when:' list (setting scene state, issuing a directive, offering choices, consulting the oracle) and a 'Do NOT use when:' list that routes to named alternatives — manage_story for recording a beat and manage_staging for presence/autonomy. This is exactly the when/when-not/alternative structure a routing agent needs.

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