cozyvtt-mcp

Dice Roll

dice_roll

Roll server-authoritative dice for a virtual tabletop campaign, publishing results to players or sending secret rolls to the roller and DM.

Instructions

Roll server-authoritative dice and publish the result to the permitted audience. Use saved_roll_list for stored expressions; saving a macro does not execute it. Authenticated campaign users may roll. Public rolls broadcast to the campaign; v1.4.0 secret rolls go to the roller and DMs, not exclusively to DMs if a player rolls. Each send creates a new roll; never retry on missing results. Calls queue with a 2.1-second minimum between actual sends; upstream allows 30 rolls/minute/user. The bridge performs no random generation or rules calculations. Returns sent:true,confirmed:false,status:"pending" inside data: dispatch is not a business ACK. Read events_poll for results/system.error and inspect state before further action; never blindly resend. 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
`purpose`	No	Optional broadcast label explaining the roll; empty string omits it, without changing dice calculation.
`is_secret`	No	False publishes to the campaign; true requests secret delivery to the roller and DMs (wire field secret).
`expression`	Yes	Server-parsed dice expression, e.g. 1d20+5, 2d6, or 4d6kh3; invalid syntax is reported asynchronously.
`character_name`	No	Optional display attribution (wire characterName), not a character ID or permission credential; null omits it.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.3.0Sep 20, 2026

addedInput schema / properties / character_name

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional display attribution (wire characterName), not a character ID or permission credential; null omits it."
+}

addedInput schema / properties / expression / description

Added value: +"Server-parsed dice expression, e.g. 1d20+5, 2d6, or 4d6kh3; invalid syntax is reported asynchronously."

addedInput schema / properties / is_secret / description

Added value: +"False publishes to the campaign; true requests secret delivery to the roller and DMs (wire field secret)."

addedInput schema / properties / purpose / description

Added value: +"Optional broadcast label explaining the roll; empty string omits it, without changing dice calculation."

Changed1 schema field changedv0.1.1Sep 8, 2026
- addedInput schema / properties / purpose
```
Added value: +{
+  "default": "",
+  "type": "string"
+}
```
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?

The description richly discloses behaviors beyond annotations: server-authoritative generation, 2.1-second queueing, 30 rolls/minute rate limit, no random generation/rules calculation by the bridge, pending-not-ACK semantics, and error response shapes. It even warns against retrying on missing results. This goes well beyond the minimal annotation signals (readOnly=false, openWorld=true, idempotent=false) and contains no contradictions.

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 adds necessary context: core purpose first, then alternatives, then behavioral constraints, then error semantics. No filler or repetition. It is structured logically and front-loaded with the most critical information.

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 tool with 4 params, 1 required, an output schema, and non-trivial queueing/error behavior, the description is complete. It covers who can use it, how to handle results asynchronously, rate limits, and exact success/failure response envelopes. Nothing critical is left to inference.

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 baseline is 3. The description adds meaning beyond the schema by clarifying async invalid-syntax reporting for expression, explaining the audience implications of is_secret (especially the v1.4.0 nuance), and stating character_name is not a credential. These additions justify a score above baseline.

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-audience statement: 'Roll server-authoritative dice and publish the result to the permitted audience.' It also distinguishes itself from saved_roll_list (stored expressions don't execute), so an agent can immediately tell it apart from the sibling tools.

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?

Explicitly names the alternative (saved_roll_list), states the precondition (authenticated campaign users), explains audience differences for public vs. secret rolls, and instructs the agent to poll events_poll for results and never blindly resend. This is clear when/when-not guidance.

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