holonovel

Session Diagnostics

manage_diagnostics

Destructive

Manage session diagnostics and maintenance: summarize or compact audit logs, verify/replay state, run visibility checks, report health, subscribe, reassign categories, and append/read events.

Instructions

Manage session diagnostics and maintenance surfaces separate from play-facing session controls. compress summarizes the audit log while compact prunes it irreversibly; verify compares live state with recorded hashes and replay reads the retained log, and both are read-only; visibility_check records its decision in the audit log while visibility_audit reads recent decisions; health, subscribe, and category reassignment do not change Novel content. compact is GM-only. Use when: reporting health, summarizing or compacting the audit log, subscribing, reassigning a category, appending/reading the event log, verifying or replaying state, or scanning a draft for GM-only disclosure. Do NOT use when: recapping play, setting verbosity, or reordering the briefing — use manage_session.

Input Schema

Name	Required	Description
`mode`	No	normal or terse (verbosity).
`text`	No	Observation text (event).
`tier`	No	Compression tier to assemble (recap; REQ-592).
`query`	No	Optional search term matched against tool name, description, and title (discover).
`action`	Yes	health, context_report, compress, compact, subscribe, category, event, history, verify, replay, visibility_check, or visibility_audit.
`detail`	No	discover response detail: summary (default) or schema (live input schemas for the matches; requires query; REQ-609).
`source`	No	Event source classification (event).
`topics`	No	Notification topics to subscribe to (subscribe).
`audience`	No	Audience badge for a visibility check (visibility_check; default the active badge).
`category`	No	New category label, or null/empty to restore the default (category).
`gm_notes`	No	GM-only free-text notes returned only to the Game Master badge (recap).
`ordinals`	No	Exact event ordinals to return in order (history; REQ-591).
`sections`	No	Ordered list of briefing sections (briefing_order).
`sessions`	No	Number of recent sessions to retain live; triggers irreversible compaction (compact; default TTRPG_AUDIT_RETENTION_SESSIONS).
`to_event`	No	Target event ordinal for replay inspection (replay; default the newest retained entry).
`supersede`	No	Ordinal of an event this observation replaces (event).
`tool_name`	No	Registered tool name to reassign (category).
`session_id`	No	Archived session id to include in recap (recap).
`max_entries`	No	Positive integer; returns a non-mutating summarize prompt over the most recent entries (compress).
`budget_tokens`	No	Positive token budget for tier assembly (recap; REQ-592) or for ledger packing (context_report; REQ-610).
`through_ordinal`	No	Return events up to and including this ordinal (history).
`include_superseded`	No	Include superseded events (history; default true).

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.

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

Changed8 schema fields changedv2026.10.13Oct 25, 2026

changedInput schema / properties / action / description

Previous value: -"health, compress, compact, subscribe, category, event, or history."New value: +"health, context_report, compress, compact, subscribe, category, event, history, verify, replay, visibility_check, or visibility_audit."

changedInput schema / properties / action / enum

Previous value: -[
-  "health",
-  "compress",
-  "compact",
-  "subscribe",
-  "category",
-  "event",
-  "history"
-]New value: +[
+  "health",
+  "context_report",
+  "compress",
+  "compact",
+  "subscribe",
+  "category",
+  "event",
+  "history",
+  "verify",
+  "replay",
+  "visibility_check",
+  "visibility_audit"
+]

addedInput schema / properties / audience

Added value: +{
+  "description": "Audience badge for a visibility check (visibility_check; default the active badge).",
+  "enum": [
+    "player",
+    "game_master",
+    "observer",
+    "none"
+  ],
+  "type": "string"
+}

addedInput schema / properties / budget_tokens

Added value: +{
+  "description": "Positive token budget for tier assembly (recap; REQ-592) or for ledger packing (context_report; REQ-610).",
+  "type": "number"
+}

addedInput schema / properties / detail

Added value: +{
+  "description": "discover response detail: summary (default) or schema (live input schemas for the matches; requires query; REQ-609).",
+  "enum": [
+    "summary",
+    "schema"
+  ],
+  "type": "string"
+}

addedInput schema / properties / ordinals

Added value: +{
+  "description": "Exact event ordinals to return in order (history; REQ-591).",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

addedInput schema / properties / tier

Added value: +{
+  "description": "Compression tier to assemble (recap; REQ-592).",
+  "enum": [
+    "recent",
+    "session",
+    "arc",
+    "campaign"
+  ],
+  "type": "string"
+}

addedInput schema / properties / to_event

Added value: +{
+  "description": "Target event ordinal for replay inspection (replay; default the newest retained entry).",
+  "type": "number"
+}

AddedOct 22, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations flag the whole tool as destructive and non-idempotent, which alone would be alarming and uninformative; the description disambiguates per action — compact's pruning is 'irreversible' and GM-only, verify and replay are read-only, visibility_check writes to the audit log while visibility_audit does not, and health/subscribe/category do not change Novel content. It also discloses the authorization constraint (GM-only) that no annotation carries.

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 per-action semantics, then the use/don't-use routing — the right order for a dispatcher tool. The per-action clauses are chained into long run-on sentences ('...and both are read-only; ...while visibility_audit reads...'), which costs some scannability, but for a 12-action tool the length is earned rather than padded.

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?

Output schema and rich annotations are present, so return values need no explanation. The description covers 11 of the 12 actions with at least a behavioral note — `context_report` is the one action never described, and it is also one of the more obscure ones. Otherwise an agent has enough to call any of these actions safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage across 22 parameters, the schema already documents each field's meaning and the action it belongs to, so the baseline is 3. The description adds marginal value by tying actions to behaviors (e.g. compact retaining `sessions`, verify comparing hashes), but it gives no syntax, defaults, or interaction detail beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific framing — 'session diagnostics and maintenance surfaces separate from play-facing session controls' — and then enumerates what nearly every action does (compress summarizes, compact prunes, verify compares hashes, replay reads, visibility_check records, visibility_audit reads). It also names the sibling it is not (manage_session), so an agent can route without opening the schema. The only slight weakness is that a 12-action grab-bag (health, subscribe, category reassignment, visibility audit) doesn't map cleanly onto a single 'diagnostics' noun, so the boundary is a little fuzzy.

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?

Explicitly structured as 'Use when:' with a full enumeration of triggering tasks, plus a 'Do NOT use when:' clause that names recapping, setting verbosity, and reordering the briefing and redirects to manage_session. This is exactly the when/when-not/alternative pattern that lets an agent choose correctly without inference.

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