cozyvtt-mcp

Session Notes Update

session_notes_update

Destructive

Update a session's shared recap without ending it. Replace notes for any existing session ID, or clear them with empty text, so campaign members see current information.

Instructions

Replace a session's shared recap without another lifecycle transition (DM only). Use session_list to find the ID; use session_manage to start/pause/end instead. All campaign members can read notes. Empty text after upstream trimming clears the recap, unlike empty notes on session_manage end. Does not end the session or broadcast a recap event. Repeated writes may alter metadata, so full-operation idempotency is not guaranteed. 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	Default
`notes`	Yes	Complete replacement recap, at most 2000 characters before trimming; empty or whitespace-only text clears it upstream.
`session_id`	Yes	Existing session ID in the configured campaign, obtained with session_list; need not be the active session.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.0Sep 20, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already signal destructive and non-idempotent behavior, and the description adds meaningful details: repeated writes may alter metadata, empty text clears the recap, the tool does not end the session or broadcast a recap event, and it explains the distinction from session_manage. No contradiction with 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?

Every sentence is informative and earns its place. The description front-loads the core purpose, then gives usage routing, behavioral caveats, and return/error semantics in a compact but complete block.

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?

Given the tool's destructive and non-idempotent nature, the description is remarkably complete: it covers lifecycle impact, permissions, ID discovery, clearing behavior, idempotency caveat, return shape on success, tool-body failures, and schema-error handling. Nothing essential 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 the baseline is 3. The description adds a useful edge-case nuance by explaining that empty text clears the recap 'unlike empty notes on session_manage end,' and it reinforces the complete-replacement semantics. This goes slightly beyond the schema, but most parameter meaning is already present there.

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 states a specific verb and resource: 'Replace a session's shared recap.' It also distinguishes itself from the lifecycle tool by saying 'without another lifecycle transition' and later 'Does not end the session or broadcast a recap event.' This clearly differentiates it from session_manage.

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?

It gives explicit direction: use session_list to find the ID, and use session_manage to start/pause/end instead. It also notes the DM-only restriction and clarifies that all campaign members can read notes, which helps an agent decide whether this tool is appropriate for the situation.

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