cozyvtt-mcp

Map Create

map_create

Create a campaign map using existing image assets (DM only). Use map_list to inspect existing maps and map_switch to activate one; creation does not switch the current map.

Instructions

Create a campaign map using existing image assets (DM only). Use map_list to inspect existing maps and map_switch to activate one; creation does not switch the current map. This creates a map with empty tokens and annotations, not an uploaded image. Upstream checks image access and normalizes asset URLs. Newer servers require MAP image assets, cap width/height at 500 squares, and default grid sizes outside 10..500 to 50. These limits are server-enforced. Each accepted call creates another map; do not blindly retry an uncertain result. CozyVTT supplies fogEnabled, globalIllumination, and explorationEnabled defaults (false); this tool intentionally has no inputs for them. Returns upstream {map} in data without a broadcast receipt. REST validation and permission errors retain upstream diagnostics. 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
`name`	Yes	Nonblank display name for the new map; upstream trims it.
`width`	Yes	Map width as a positive integer, in grid units.
`height`	Yes	Map height as a positive integer, in grid units.
`grid_size`	No	Positive integer pixels per grid square; defaults to 50.
`image_url`	Yes	Existing map image asset ID or URL; upstream checks asset access. No file upload.
`spirit_layer_url`	No	Optional existing spirit-layer image asset ID or URL; null omits it.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Sep 20, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description reinforces rather than repeats them by explaining the consequence: every accepted call produces a new map, so retries duplicate state. It also discloses the empty-token/empty-annotation initial state, upstream asset-access checks, server-enforced clamping of width/height and grid defaults, fixed false defaults for fog/illumination/exploration with no inputs to change them, and the difference between REST permission errors and tool-body failures.

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 and sibling routing are front-loaded, and every sentence carries operational content. It is dense to the point of being a wall of text, however, and the return-value/error sentences could be tightened given an output schema 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?

For a six-parameter non-idempotent mutation with an output schema, it covers everything an agent needs: assets must pre-exist (no upload), DM-only authorization, clamping behavior, non-idempotency, and the split between upstream diagnostics and {ok:false} tool-body errors.

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 real meaning the schema cannot express: dimensions are capped at 500 squares and grid sizes outside 10..500 are coerced to 50, both server-enforced. It also explains that fogEnabled/globalIllumination/explorationEnabled are deliberately absent as inputs, pre-empting a hunt for missing parameters.

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?

Opens with a specific verb and resource plus a scope qualifier: "Create a campaign map using existing image assets (DM only)." It immediately distinguishes itself from map_list and map_switch, and the phrase "not an uploaded image" rules out a plausible misreading of image_url.

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 routes the agent: use map_list to inspect, map_switch to activate, and notes that creation does not switch the current map. It also gives a genuine when-not-to-call rule: "Each accepted call creates another map; do not blindly retry an uncertain result," which directly explains the non-idempotent annotation.

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