Skip to main content
Glama

Agent Task Management

manage_agent
Destructive

Create, advance, complete, fail, cancel, list, or inspect durable NPC/agent tasks and their action lifecycle; mutations persist to campaign state and are audited.

Instructions

Manage durable NPC/agent tasks and their action lifecycle. create reads goal and optional source_goal; advance requires task_id and appends description; complete, fail, and cancel require task_id, settle the task without deleting it, and terminal tasks are immutable; autonomy defaults to TTRPG_AGENT_AUTONOMY. Mutating actions persist to the Novel and are audited; list/get are read-only. Use when: creating, starting, advancing, settling, or inspecting tasks. Do NOT use when: surfacing an advisory suggestion — use manage_scene (action: oracle); managing NPC identity — use manage_npc. 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_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
goalNoTask goal text (create).
actionYescreate, list, get, start, advance, complete, fail, or cancel.
detailNoReturn full agent tasks instead of summary entries (list).
subjectNoEntity or NPC that owns the task (create/list).
task_idNoTask id (get/start/advance/complete/fail/cancel).
autonomyNoadvisory, prompt, or auto (create; default the TTRPG_AGENT_AUTONOMY setting).
descriptionNoAction description (advance).
source_goalNoOriginating goal-pursuit suggestion (create).

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.13
    • addedInput schema / properties / detail
      Added value: +{
      +  "description": "Return full agent tasks instead of summary entries (list).",
      +  "type": "boolean"
      +}
  2. Addedv1.0.3

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds real context beyond them: settling does not delete the task, terminal tasks are immutable, mutations persist to the Novel and are audited, and list/get are read-only. Minor gap: it does not say what happens on invalid transitions (e.g., advancing a terminal task) or whether advance requires the task to be in a started state.

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, then action semantics, then use/don't-use routing and the revert path — a sensible order. It is dense and slightly redundant with the schema's per-action hints (repeating which actions require task_id), which costs a point but the content is not padded.

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 an 8-param multi-action tool with an output schema, the description covers action semantics, defaults, persistence/audit behavior, read-only vs mutating split, sibling routing, and the undo path. Since return values are handled by the output schema, nothing an agent needs to invoke this 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 per-parameter meaning is already covered and 3 would be the baseline. The description still adds value by grouping parameters per action (create reads goal/source_goal; advance requires task_id and appends description) and by clarifying that description is appended rather than overwritten, plus the autonomy default source.

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 durable NPC/agent tasks and their action lifecycle") and then enumerates the full action set (create, advance, complete, fail, cancel, list, get, start). It differentiates itself from siblings explicitly, naming manage_scene (action: oracle) and manage_npc as the wrong tools for adjacent needs.

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?

Provides both a positive trigger list ("Use when: creating, starting, advancing, settling, or inspecting tasks") and explicit exclusions with the correct alternative for each (advisory suggestion → manage_scene: oracle; NPC identity → manage_npc). It also names the recovery path (manage_history: undo), leaving nothing for the agent to infer.

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