holonovel

Combat Encounter Management

manage_combat

Destructive

Instructions

Manage combat encounters in the active Novel — encounter turn order, participants, and lifecycle, not per-entity conditions. Mutating actions persist to the Novel and are audited; read-only actions do not mutate state. Revert the most recent mutation with manage_history (action: undo). init's seed only reorders the danger set; participants keep their given order. Use when: starting, advancing, ending a fight, or changing its participants. Do NOT use when: applying a status effect — use manage_condition (action: apply).

Input Schema

Name	Required	Description
`seed`	No	Optional deterministic seed (init).
`action`	Yes	init, advance, end, add_participant, remove_participant, or status.
`dangers`	No	Optional non-entity combatants (init).
`outcome`	No	Optional text describing how combat ended (end).
`participants`	No	Entity identifiers participating (init).
`participant_id`	No	Entity identifier (add_participant/remove_participant).

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.

Addedv1.0.3Sep 29, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond annotations (destructive=true, non-idempotent), it discloses that mutating actions persist and are audited, that read-only actions do not mutate state, that the last mutation can be reverted with manage_history undo, and the subtle seed rule (seed only reorders the danger set; participants keep their given order). That is exactly the behavioral context a destructive-but-revertible tool needs.

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?

Four tightly packed sentences, front-loaded with purpose and scope, then mutation/audit semantics, then seed nuance, then explicit use/do-not-use directives. No filler and no repetition of the enum list already in the schema.

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?

For a 6-parameter mutation tool with an output schema, the description supplies everything the schema cannot: scope, mutation/audit behavior, undo path, a non-obvious seed semantic, and a sibling routing rule. Nothing an agent needs before calling it appears 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 description coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot: the deterministic seed's actual effect on ordering and the fact that participants retain their supplied order on init. It doesn't touch outcome/dangers, but those are adequately documented inline.

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 a specific verb and resource ("Manage combat encounters in the active Novel") and immediately bounds the scope as encounter-level turn order, participants, and lifecycle "not per-entity conditions." This scope boundary lets an agent separate it from manage_condition without opening either 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?

Explicit "Use when: starting, advancing, ending a fight, or changing its participants" and "Do NOT use when: applying a status effect — use manage_condition (action: apply)." It also names the recovery path via manage_history (action: undo), so both the trigger and the alternatives are covered.

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