Skip to main content
Glama

Countdown Manager

manage_countdown
Destructive

Create, advance, list, or remove countdown timers in the active Novel; timers can fire a world effect at their threshold and auto-advance on scene transitions.

Instructions

Manage countdown timers in the active Novel. set accepts a starting tick count and optional total; advance fires the configured world_effect when the countdown reaches its threshold, and on_scene_transition advances it automatically; direction shifts NPC dispositions only when scope is also set. remove is GM-only and deletes the timer without firing its world_effect. Mutating actions persist to the Novel and are audited; list is read-only. Use when: starting, advancing, removing, or listing clocks. Do NOT use when: tracking a vow's progress — use manage_vow (action: milestone). Revert with manage_history (action: undo).

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_countdown"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoCountdown name (set/advance/remove).
typeNoround or narrative (set).
scopeNoOptional scope name (set).
ticksNoStarting ticks (set).
totalNoOptional capacity for decrement refills (set; defaults to ticks).
actionYesset, advance, remove, or list.
survivalNoSurvival-resource parameters applied when a room hazard names this countdown (set; REQ-622c).
triggersNoOptional world-model triggers (set).
directionNoOptional direction: increment or decrement (set).
world_effectNoOptional world-model effect applied when the countdown fires (set).
on_scene_transitionNoWhen true, advance on each scene transition (set).

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. Changed1 schema field changedv2026.10.18
    • addedInput schema / properties / survival
      Added value: +{
      +  "description": "Survival-resource parameters applied when a room hazard names this countdown (set; REQ-622c).",
      +  "properties": {
      +    "bundle_increment": {
      +      "description": "Ticks a bundle adds when taken (REQ-622c).",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "last_light_ticks": {
      +      "description": "Length of the last-light countdown (REQ-622c).",
      +      "minimum": 1,
      +      "type": "number"
      +    },
      +    "light_thing": {
      +      "description": "Thing whose lit state is the resource's light (REQ-622c).",
      +      "type": "string"
      +    },
      +    "per_use_decrement": {
      +      "description": "Ticks one scene-transition use subtracts (REQ-622c).",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "unit_countdown": {
      +      "description": "Countdown spent per relight (REQ-622c).",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed2 schema fields changedv2026.10.13
    • changedInput schema / properties / ticks / minimum
      Previous value: -1New value: +0
    • addedInput schema / properties / total
      Added value: +{
      +  "description": "Optional capacity for decrement refills (set; defaults to ticks).",
      +  "minimum": 1,
      +  "type": "number"
      +}
  3. Addedv1.0.3

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say the tool is destructive and not read-only; the description goes much further by specifying that advance fires the configured world_effect, that remove is GM-only and deletes WITHOUT firing world_effect, and that mutating actions both persist to the Novel and are audited. These are exactly the irreversible-consequence and permission facts an agent needs before calling a destructive tool.

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 the core purpose and then scoped per action, with zero filler sentences. It is dense — one long semicolon-chained sentence carries most of the behavioral detail — which is efficient but slightly harder to scan than bulleted action notes would be.

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?

For an 11-parameter tool with nested objects and an output schema, the description covers the action model, mutation persistence, GM-only restriction, side-effect firing, and sibling exclusions, so calling it correctly is feasible from the definition. The remaining omission is how the nested survival and triggers blocks relate to room hazards; the schema names them but the description never ties them to a hazard-triggered lifecycle.

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 a real cross-parameter rule the schema does not state: direction shifts NPC dispositions only when scope is also set, and advance auto-fires via on_scene_transition. It says nothing about survival, triggers, or world_effect sub-fields, which the schema documents on its own but whose interaction with advance/remove is left implicit.

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 countdown timers in the active Novel") and then breaks the four actions apart: set creates from a starting tick count, advance fires world_effect at threshold, remove deletes, list is read-only. An agent can distinguish this from every sibling without inspecting the 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" and "Do NOT use when" blocks, with the near-miss case (vow progress) routed to manage_vow with the exact action argument, plus manage_history (undo) for reverting. The only minor gap is that advance-vs-set timing is described in the behavioral prose rather than as a selection rule.

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