holonovel

NPC Management

manage_npc

Destructive

Manage NPCs in a tabletop RPG campaign: create, update, remove, list, or get characters, with GM-only mind details and audited, undoable changes.

Instructions

Manage non-player characters in the active Novel. create requires a name; ruleset_reference links a stat block without copying it; mind is GM-only and never returned to the Player badge; remove deletes the NPC permanently. create, update, and remove require the GM or Editor badge, persist to the Novel, are audited, and are undoable via manage_history (action: undo); list and get are read-only. Use when: introducing, revising, removing, listing, or reading NPCs. Do NOT use when: managing player characters — use manage_character (action: create/import/sheet).

Input Schema

Name	Required	Description
`card`	No	Character Card V3 JSON object or string (import_card).
`mind`	No	Optional GM-only NPC mind (create/update).
`name`	No	NPC name (create).
`goals`	No	Optional goals.
`action`	Yes	create, update, remove, list, get, import_card, or export_card.
`detail`	No	Return full NPC records instead of summary entries (list).
`npc_id`	No	NPC identifier (update/remove/get/export_card).
`source`	No	Import provenance URL or description (import_card).
`license`	No	Import license attestation (import_card).
`persona`	No	Optional values, traits, and mannerisms (create/update).
`location`	No	Optional location.
`description`	No	Optional description.
`disposition`	No	Optional disposition.
`confirm_lore`	No	Import the card's character_book as lore entries (import_card).
`talkativeness`	No	Optional 0-100 social-scene speaking weight; default 50 (create/update).
`ruleset_reference`	No	Optional ruleset stat-block reference (create).

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.

Changed12 schema fields changedv2026.10.13Oct 25, 2026

changedInput schema / properties / action / description

Previous value: -"create, update, remove, list, or get."New value: +"create, update, remove, list, get, import_card, or export_card."

changedInput schema / properties / action / enum

Previous value: -[
-  "create",
-  "update",
-  "remove",
-  "list",
-  "get"
-]New value: +[
+  "create",
+  "update",
+  "remove",
+  "list",
+  "get",
+  "import_card",
+  "export_card"
+]

addedInput schema / properties / card

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    }
+  ],
+  "description": "Character Card V3 JSON object or string (import_card)."
+}

addedInput schema / properties / confirm_lore

Added value: +{
+  "description": "Import the card's character_book as lore entries (import_card).",
+  "type": "boolean"
+}

addedInput schema / properties / detail

Added value: +{
+  "description": "Return full NPC records instead of summary entries (list).",
+  "type": "boolean"
+}

addedInput schema / properties / license

Added value: +{
+  "description": "Import license attestation (import_card).",
+  "type": "string"
+}

addedInput schema / properties / mind / properties / identity_core

Added value: +{
+  "description": "Stable values, bonds, and taboos (GM only).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / mind / properties / shared_notes

Added value: +{
+  "description": "Always-known facts (GM only).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / npc_id / description

Previous value: -"NPC identifier (update/remove/get)."New value: +"NPC identifier (update/remove/get/export_card)."

addedInput schema / properties / persona

Added value: +{
+  "description": "Optional values, traits, and mannerisms (create/update).",
+  "type": "string"
+}

addedInput schema / properties / source

Added value: +{
+  "description": "Import provenance URL or description (import_card).",
+  "type": "string"
+}

addedInput schema / properties / talkativeness

Added value: +{
+  "description": "Optional 0-100 social-scene speaking weight; default 50 (create/update).",
+  "maximum": 100,
+  "minimum": 0,
+  "type": "number"
+}

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?

Goes well beyond the annotations: states that create requires a name, that ruleset_reference links a stat block without copying it, that mind is GM-only and never returned to the Player badge, that remove is permanent deletion, and that writes require GM/Editor badge, persist, are audited, and are undoable via manage_history. The destructiveHint=true annotation is corroborated rather than contradicted.

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 semicolon-delimited clauses with zero filler; purpose comes first, per-action semantics next, then when/when-not routing. Everything stated is decision-relevant for a 16-parameter tool.

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?

Covers permissions, persistence, audit/undo, visibility, and destructive behavior for the core actions, and an output schema exists so return values need no explanation. Minor gaps: import_plan/import/export operations (card, source, license, detail) get no behavioral framing such as where card data lands or what confirm_lore does.

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 real value on top by explaining the semantics of name (required on create), ruleset_reference (reference, not copy), and mind (GM-only, hidden from players), which the schema only labels. It does not add meaning for import_card parameters like license/source or confirm_lore.

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?

Opens with a specific verb+resource ("Manage non-player characters in the active Novel") and then enumerates the action surface (create/update/remove/list/get plus card import/export). It explicitly distinguishes itself from the nearest sibling, manage_relationship-style confusion avoided by calling out 'use manage_relationship' equivalent for NPCs.

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 an explicit "Use when:" list and a "Do NOT use when:" exclusion that names the alternative (manage_character with its create/import/sheet actions). An agent can route between NPC and PC management without opening either schema.

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