cozyvtt-mcp

Events Poll

events_poll

Read-onlyIdempotent

Read buffered CozyVTT campaign events and asynchronous write errors without consuming them, so you can inspect pending WS writes and page through updates by sequence.

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. v1.5.0 role/map/token notifications are also forwarded; drag frames remain observations, not proof of persisted state. 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

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

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

A4.8/5.0

Behavior5/5

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

Although annotations already declare readOnly/idempotent/non-destructive, the description adds substantive behavior beyond them: lazy WS connection, no game-state mutation, stale marking on connection failure, 500-event eviction buffer, cursor_reset after restart, has_more pagination, and the warning that broadcasts are not correlated ACKs. This is unusually rich disclosure for a read 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?

Purpose is front-loaded in the first clause and every sentence carries operative information, but the passage is long and some material (the ok/data envelope) duplicates the output schema. Dense rather than padded, but denser than strictly needed.

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 stateful polling tool with an output schema already present, the description still covers the non-obvious failure modes an agent must handle: eviction gaps, cursor resets, pagination, stale-on-failure, and MCP-level vs tool-body error shapes. Nothing needed to invoke it 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 the baseline is 3, but the description adds value beyond it: it explains the since/next_seq relationship ('Returns earliest seq > since first') and the resume protocol ('advance using next_seq'). It leaves the limit semantics entirely to the schema, keeping it just short of a 5.

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+resource ('Read buffered campaign events and asynchronous write errors') with the crucial scope qualifier 'without consuming them'. It explicitly distinguishes itself from the sibling chat_read, so an agent can route without opening either 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?

Gives an explicit trigger ('Use after WS writes') and names the alternative plus its selecting condition ('use chat_read for persisted chat history'). It further excludes a wrong use case ('this is not durable dice history'), which is the strongest form of when-not guidance.

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