cozyvtt-mcp

Session Manage

session_manage

Destructive

Start, pause, or end a campaign session as DM, with optional recap notes and end-of-session state snapshot.

Instructions

Start, pause, or end a campaign session through REST (DM only). Use session_list to inspect history and session_notes_update to edit or clear a recap without another lifecycle transition. start creates a session; pause/end resolve campaign.activeSession.id and fail if none exists. Lifecycle changes are not guaranteed idempotent: do not repeat start/end to repair notes. notes and save_state apply only to end; other actions reject nondefault values. End notes are campaign-wide, and empty text does not clear an existing recap. save_state requests the upstream end-of-session snapshot; it is not a bridge-side backup. Returns upstream REST data; it does not wait for a WS business ACK. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Input Schema

TableJSON Schema

Name	Required	Description
`notes`	No	Shared recap for end, at most 2000 characters; null omits it. Empty end text does not clear old notes; use session_notes_update.
`action`	Yes	Lifecycle transition: start, pause, or end, case-insensitive. Pause/end target the currently active session.
`save_state`	No	True (default) requests saving state on end; false skips that snapshot. Must remain true for start/pause.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.3.0Sep 20, 2026

addedInput schema / properties / action / description

Added value: +"Lifecycle transition: start, pause, or end, case-insensitive. Pause/end target the currently active session."

addedInput schema / properties / notes

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Shared recap for end, at most 2000 characters; null omits it. Empty end text does not clear old notes; use session_notes_update."
+}

addedInput schema / properties / save_state

Added value: +{
+  "default": true,
+  "description": "True (default) requests saving state on end; false skips that snapshot. Must remain true for start/pause.",
+  "type": "boolean"
+}

First observedv0.1.0Sep 5, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already say destructiveHint=true and idempotentHint=false, but the description goes further: it explains non-idempotency in practical terms, discloses that notes and save_state apply only to end, and clarifies that save_state is not a bridge-side backup. It also warns that empty end text does not clear an existing recap and that the tool does not wait for a WS business ACK. These are meaningful behavioral nuances beyond the annotations.

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?

The description is dense but every sentence earns its place: purpose, sibling routing, lifecycle rules, notes/save_state constraints, and return format. It is front-loaded with the core action and ends with structured return behavior, with no fluff or repetition.

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 non-idempotent, destructive, state-changing tool with conditional parameters, the description covers what is needed: when each action applies, what fails, how notes and save_state behave differently per action, return success/error shapes, and the DM-only restriction. The presence of an output schema means detailed return fields are not required, and the description still summarizes the success/error envelope.

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%, which establishes a baseline of 3. The description adds extra semantics beyond the schema: notes are 'campaign-wide', nondefault notes/save_state values are rejected for start/pause, and save_state requests an 'upstream' snapshot rather than a local backup. These details enhance understanding of all three parameters, so a score above baseline is warranted.

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?

The description opens with a specific verb-resource pair ('Start, pause, or end a campaign session') and immediately scopes the tool to 'REST (DM only)', which clearly distinguishes it from read-only or notes-related tools. It also explicitly names the two most relevant siblings (session_list and session_notes_update), so an agent can differentiate without inspecting schemas.

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?

The description explicitly instructs when to use alternatives: 'Use session_list to inspect history and session_notes_update to edit or clear a recap without another lifecycle transition.' It also explains that pause/end fail if no active session exists, and warns against repeating start/end to repair notes because changes are not idempotent. This is concrete, actionable usage guidance.

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