cozyvtt-mcp

Token Move

token_move

Destructive

Instructions

Set an existing token's absolute position through REST. Use token_add to create a token or map_switch to change the active map. The bridge rejects SPECTATOR/unknown roles; upstream requires DM or the controlling player. The same coordinates produce the same position, but repeated writes may produce notifications. Returns persisted=true,broadcast_confirmed=false; REST does not itself emit map.changed. On both REST and WS token.move, PLAYER must use the current campaign map; DM may use any map of this campaign. Upstream applies control, plane, and session-state restrictions; returned token fields may be null. Newer servers require whole-square coordinates and may clamp the footprint at map edges. Read the returned position rather than assuming the requested one. Inspect events_poll or the VTT before assuming others saw the move; this result is not a correlated broadcast ACK. 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
`x`	Yes	Absolute horizontal position in map units; upstream requires 0 <= x < map width.
`y`	Yes	Absolute vertical position in map units; upstream requires 0 <= y < map height.
`map_id`	Yes	Map ID containing the existing token. On both REST and WS token.move, PLAYER must use the current campaign map; DM may use any map of this campaign.
`token_id`	Yes	Existing token ID on that map; this is not a character or creature ID.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.5.0Oct 7, 2026

changedInput schema / properties / map_id / description

Previous value: -"Map ID containing the existing token, not necessarily the active map."New value: +"Map ID containing the existing token. On both REST and WS token.move, PLAYER must use the current campaign map; DM may use any map of this campaign."

Changed4 schema fields changedv0.3.0Sep 20, 2026

addedInput schema / properties / map_id / description

Added value: +"Map ID containing the existing token, not necessarily the active map."

addedInput schema / properties / token_id / description

Added value: +"Existing token ID on that map; this is not a character or creature ID."

addedInput schema / properties / x / description

Added value: +"Absolute horizontal position in map units; upstream requires 0 <= x < map width."

addedInput schema / properties / y / description

Added value: +"Absolute vertical position in map units; upstream requires 0 <= y < map height."

First observedv0.1.0Sep 5, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With annotations present, the description still adds substantial non-structured context: bridge role rejection, upstream control/plane/session restrictions, null token fields, whole-square coordinate enforcement, footprint clamping at map edges, and the crucial caveat that the write is not a correlated broadcast ACK (broadcast_confirmed=false, no map.changed emitted by REST). It also explains why repeated identical writes are not a no-op (notifications), which reconciles with idempotentHint=false rather than contradicting it.

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?

Front-loaded with the core operation, and nearly every sentence adds an operational constraint or failure mode. It is dense and somewhat run-on, with the error-contract sentence trailing at the end where it is least visible, but no sentence is filler.

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 mutation tool with real upstream permission, coordinate, and broadcast semantics, the description covers preconditions, edge-case behavior, and the success/failure envelope. It goes beyond what the output schema alone conveys by warning against assuming the move was observed.

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 schema carries the per-parameter burden and 3 would be the baseline. The description still adds meaning beyond the schema: whole-square coordinate requirements on newer servers, clamping of the token footprint at map edges, and the instruction to read the returned position rather than trust the requested one. Some sentences duplicate schema text verbatim (the PLAYER/DM map line on map_id).

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 and resource with scope: "Set an existing token's absolute position through REST." It immediately distinguishes itself from token_add (creation) and map_switch (active map), so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the sibling alternatives explicitly (token_add for creating, map_switch for changing the active map) and states the role conditions under which this tool applies (DM may use any campaign map, PLAYER only the current campaign map). It also points to events_poll/VTT as the verification path. It stops short of explicitly stating exclusion cases for the move itself, so a 4 rather than 5.

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