holonovel

Faction Management

manage_faction

Destructive

Create, update, remove, or list factions in the active Novel with names, goals, resources, and territory references. Use it to maintain faction records; changes are undoable via history.

Instructions

Manage organizations in the active Novel: create, update, remove, or list factions, each carrying a name, description, goals, resources, and optional territory room names. name is required to create and faction_id targets an existing faction; the progress clock is Novel-internal and not set directly. create, update, and remove require the GM or Editor badge, persist to the Novel, and are undoable via manage_history (action: undo); remove deletes the faction permanently unless undone, and list is read-only. Use when: creating, revising, removing, or listing factions. Do NOT use when: tracking a faction's territory rooms — use manage_world (action: create_room).

Input Schema

Name	Required	Description
`name`	No	Faction name (create).
`goals`	No	Optional goals.
`action`	Yes	create, update, remove, or list.
`detail`	No	Return full faction records instead of summary entries (list).
`resources`	No	Optional resources.
`territory`	No	Optional territory names.
`faction_id`	No	Faction identifier (update/remove).
`description`	No	Optional description.

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.

Changed1 schema field changedv2026.10.13Oct 25, 2026

addedInput schema / properties / detail

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

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 annotations: states the GM/Editor badge requirement, that changes persist to the Novel, that they're undoable via manage_history (action: undo), that remove is permanent unless undone, that list is read-only, and that the progress clock is Novel-internal and not settable. Annotations confirm destructiveHint=true and this adds the recovery path.

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-loads the operation set, then permissions/undo behavior, then usage routing. Dense but nearly every clause carries information; the only mild waste is restating 'create, update, remove, or list' inside the 'Use when' clause.

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?

Multi-action mutation tool with an output schema and rich annotations, yet the description still covers authorization, persistence, undo, and destructive semantics. Nothing an agent needs to call it correctly is missing.

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 action-parameter pairing ('name is required to create', 'faction_id targets an existing faction') and an explicit exclusion (progress clock not set directly) that the per-field schema strings do not convey.

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?

States specific verbs (create, update, remove, list) against a specific resource (factions in the active Novel) and enumerates the fields carried. An agent can distinguish it from manage_world/manage_novel based on the description alone.

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?

Explicit 'Use when' clause enumerates the four triggering actions, and a 'Do NOT use when' clause names the alternative (manage_world action: create_room) for territory-room tracking. Both positive and negative routing are present.

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