cozyvtt-mcp

Dice Roll

dice_roll

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.

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.5.0 permits DM and PLAYER rolls, not spectators; secret routing and the shared user budget remain server-authoritative. Each send creates a new roll; never retry on missing results. Calls queue with a 2.1-second minimum between actual sends, retaining the older 30/minute policy. Newer servers allow higher rates but cap characterName at 200 and purpose at 300 characters; server errors remain visible through events_poll. 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

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

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.8/5.0

Behavior5/5

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

Annotations already flag non-readOnly, open-world and non-idempotent, but the description adds substantially: a 2.1-second minimum gap with 30/minute, the server-authoritative budget and secret routing, and the crucial disclosure that sent:true/confirmed:false is a dispatch, not a business ACK. It also clarifies that the bridge performs no RNG or rules math and points to events_poll for error visibility.

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?

The core routing rule and the send/ACK caveat are front-loaded in the first few sentences, and every clause carries operational value. It is dense and slightly sprawling, with error-shape details tacked on at the end, but there is no obvious filler to cut.

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, open-world mutation tool, the description covers permissions, rate limits, delivery semantics, failure handling, and where to observe results. With an output schema present, it need not explain return values, and it still documents the success/failure envelope shape and MCP-vs-tool error distinction.

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 four parameters are already documented, and the description still adds field-level constraints the schema omits: characterName capped at 200 and purpose at 300 characters on newer servers, plus that purpose does not alter dice calculation. It does not restate the expression grammar, which is fine since the schema covers it.

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 opening sentence states a specific verb+resource ('Roll server-authoritative dice') plus the side effect ('publish the result to the permitted audience'), which no sibling tool offers. It also explicitly distinguishes itself from saved_roll_list, so an agent can route between them without opening 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?

Explicitly names the alternative for stored expressions ('use saved_roll_list'), warns that saving a macro is not execution, states who may roll (authenticated campaign users; DM/PLAYER, not spectators), and gives an operational rule ('never retry on missing results'). These are concrete when-to-use/when-not conditions rather than implied guidance.

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