create-tiles

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

With no annotations provided, the description carries the full behavioral burden, and it excels: it discloses coordinate conversion to v14's center-anchored doc coords, warns against pre-adding width/2, explains per-tile error isolation with 404 behavior, states that created ids are returned, and notes the GM-only restriction. This goes well beyond the schema and title.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: purpose first, coordinate semantics second, optional capabilities next, then error behavior, return value, and permission. Each sentence adds distinct value, and nothing is wasted or redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's complexity and lack of an output schema, the description covers placement semantics, coordinate conversion, optional behaviors, error isolation, return value, and GM-only access. It is complete enough for an agent to call the tool correctly, especially with the fully described input schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds meaningful integrated guidance about how parameters relate: width/height define on-map canvas size, x/y are absolute-canvas top-left, occlusionMode 1/4 makes roofs fade under tokens, and scaleX/scaleY zoom the texture inside the frame rather than resizing the tile. This extra context earns a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Place') and a specific resource ('TILES') while enumerating tile subtypes (props, roofs/overhead pieces, decals, video overlays), which clearly separates it from sibling tools like place-tokens or create-drawings. It also names the scene as the target and the data-relative path source, so the tool's scope is unambiguous.

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

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

The description clearly implies this tool is for placing tiles on scenes, and it points to get-scene-dimensions for coordinate math, which is helpful context. However, it does not explicitly state when to prefer this over alternatives such as update-tiles, delete-tiles, or place-tokens, nor does it give any when-not-to-use guidance.

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