Skip to main content
Glama

Session Diagnostics

manage_diagnostics
Destructive

Manages session diagnostics and maintenance: summarize or prune audit logs, verify or replay recorded state, report token usage, and audit GM-only visibility while leaving play content unchanged.

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; context_report emits a per-section token ledger and accepts budget_tokens to pack it; 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 or context size, 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_context.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "manage_diagnostics"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNonormal or terse (verbosity).
textNoObservation text (event).
tierNoCompression tier to assemble (recap; REQ-592).
queryNoOptional search term matched against tool name, description, and title (discover).
actionYeshealth, context_report, compress, compact, subscribe, category, event, history, verify, replay, visibility_check, or visibility_audit.
detailNodiscover response detail: summary (default) or schema (live input schemas for the matches; requires query; REQ-609).
formatNoRecap/compress output notation (recap, compress; default markdown; REQ-072g).
sourceNoEvent source classification (event).
topicsNoNotification topics to subscribe to (subscribe).
audienceNoAudience badge for a visibility check (visibility_check; default the active badge).
categoryNoNew category label, or null/empty to restore the default (category).
gm_notesNoGM-only free-text notes returned only to the Game Master badge (recap).
ordinalsNoExact event ordinals to return in order (history; REQ-591).
sectionsNoOrdered list of briefing sections (briefing_order).
sessionsNoNumber of recent sessions to retain live; triggers irreversible compaction (compact; default TTRPG_AUDIT_RETENTION_SESSIONS).
to_eventNoTarget event ordinal for replay inspection (replay; default the newest retained entry).
max_rollsNoSignificant rolls to return, bounded 1–50 (recap; default 5; REQ-072e).
supersedeNoOrdinal of an event this observation replaces (event).
tool_nameNoRegistered tool name to reassign (category).
session_idNoArchived session id to include in recap (recap).
max_entriesNoPositive integer; returns a non-mutating summarize prompt over the most recent entries (compress).
budget_tokensNoPositive token budget for tier assembly (recap; REQ-592) or for ledger packing (context_report; REQ-610).
max_transitionsNoScene transitions to return, bounded 1–20 (recap; default 5; REQ-072e).
through_ordinalNoReturn events up to and including this ordinal (history).
include_supersededNoInclude superseded events (history; default true).

Output Schema

NameRequiredDescriptionDefault
textNoHuman-readable text envelope mirroring the structured result (REQ-001, REQ-548a).
statusYesMachine-readable result status: OK, NEED_INPUT, WARNING, PARTIAL, or an error category (REQ-002, REQ-548c).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2026.10.18
    • addedInput schema / properties / format
      Added value: +{
      +  "description": "Recap/compress output notation (recap, compress; default markdown; REQ-072g).",
      +  "enum": [
      +    "markdown",
      +    "lonelog"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / max_rolls
      Added value: +{
      +  "description": "Significant rolls to return, bounded 1–50 (recap; default 5; REQ-072e).",
      +  "type": "number"
      +}
    • addedInput schema / properties / max_transitions
      Added value: +{
      +  "description": "Scene transitions to return, bounded 1–20 (recap; default 5; REQ-072e).",
      +  "type": "number"
      +}
  2. Changed2 schema fields changedv2026.10.15
    • removedInput schema / properties / category / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / category / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  3. Changed8 schema fields changedv2026.10.13
    • 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"
      +}
  4. Added

TDQS

A4.1/5.0
Behavior4/5

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

Adds substantial context beyond the annotations: it states that compact is irreversible and GM-only, that verify/replay are read-only, that visibility_check writes an audit record while visibility_audit is a read, and that health/subscribe/category leave Novel content untouched. This is real behavioral disclosure for a tool whose annotations only give a blanket destructiveHint=true. It stops short of describing what the returned diagnostics or audit entries look like, though an output schema exists.

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?

Scope is front-loaded in the first sentence and every subsequent clause carries action-specific information. However, the action summary and the 'Use when' list overlap (event log reading/appending appears twice), and the long semicolon-chained sentence requires re-reading to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-action, 25-parameter tool, several actions (health, event, history, category, subscribe) are only indirectly characterized — mostly via the negative statement that they do not change Novel content, rather than by saying what they return or require. The high-risk actions are well covered, but an agent still cannot tell from the description what health or history actually produce without consulting 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 goes further by explaining cross-parameter behavior the schema does not: budget_tokens is what context_report accepts to pack the ledger, and sessions is what triggers irreversible compaction on compact. Those linkages help an agent pick values rather than just types.

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 opening sentence names a concrete resource (session diagnostics and maintenance surfaces) and scopes it against play-facing controls, which is meaningful distinction. The body then spells out what each of the twelve actions does (compress summarizes, compact prunes irreversibly, verify compares hashes, context_report emits a token ledger). It is specific, but the umbrella label 'manage' plus a dozen heterogeneous actions means an agent must read the whole paragraph to know what the tool is.

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 both directions: a 'Use when' list enumerating the triggering situations and a 'Do NOT use when' clause that names the alternative tool (manage_context) for recapping, verbosity, and briefing order. This is exactly the when/when-not/alternative structure that prevents misrouting among many similarly named siblings.

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