cozyvtt-mcp

Events Poll

events_poll

Read-onlyIdempotent

Read buffered campaign events and async write errors without consuming them. Advance with next_seq and check has_more for pagination.

Instructions

Read buffered campaign events and asynchronous write errors without consuming them. Use after WS writes; use chat_read for persisted chat history. May connect WS lazily, but does not change game state. Returns earliest seq > since first; advance using next_seq (latest_seq is its alias), not high_water_seq. Check gap for eviction from the 500-event buffer, cursor_reset after process restart, and has_more for pagination. Inspect system.error and relevant state to assess pending writes; broadcasts are not correlated ACKs. Buffered events remain available on connection failure, marked stale; this is not durable dice history. Repeated reads can include newly arriving events. 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
`limit`	No	Maximum events per page, 1..500; defaults to 100. Continue with next_seq when has_more is true.
`since`	No	Last next_seq received, integer >=0; 0 starts at the oldest retained event. A cursor beyond this process resets to 0.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.3.0Sep 20, 2026

addedInput schema / properties / limit / description

Added value: +"Maximum events per page, 1..500; defaults to 100. Continue with next_seq when has_more is true."

addedInput schema / properties / since / description

Added value: +"Last next_seq received, integer >=0; 0 starts at the oldest retained event. A cursor beyond this process resets to 0."

First observedv0.1.0Sep 5, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already mark this readOnly, idempotent, and non-destructive, and the description reinforces and enriches these with critical context: events are not consumed, connection may be lazy, game state is unchanged, buffer eviction is 500 events, cursor reset happens after process restart, and stale events remain available. This goes far beyond what annotations provide.

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?

Although dense, every sentence carries distinct content—purpose, usage, cursor mechanics, buffer semantics, error behavior, and return shape. The most important behavioral facts are front-loaded, and no filler or repetition exists.

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 complexity, the description is remarkably complete: it covers consumption semantics, async error inspection, pagination, buffer eviction, connection failure behavior, non-durability, return shapes, failure modes, and MCP error handling. An agent has enough to call it correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds valuable semantic detail beyond the schema: 'Returns earliest seq > since first', 'advance using next_seq (latest_seq is its alias), not high_water_seq', and explains gap, cursor_reset, and has_more. This meaningfully informs correct parameter use.

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 action and resource: 'Read buffered campaign events and asynchronous write errors without consuming them.' It explicitly distinguishes itself from chat_read ('use chat_read for persisted chat history') and clearly describes the non-mutating nature of the tool.

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 direct when-to-use guidance: 'Use after WS writes' and names the alternative for chat history ('use chat_read for persisted chat history'). It also explains cursor advancement, pagination, and buffer behavior, leaving little ambiguity about how the tool should be used.

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