Preview Wang terrain edits

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

The description adds substantial detail beyond annotations (readOnlyHint=true, destructiveHint=false): it explains the exact semantics of setWangTiles (all-zero wangId removes, identical is no-op, upsert otherwise), the clockwise order of slots, 1-based color indexes, and the rewriting of the touched wangtiles member in canonical order. It also discloses the expiring nature and fail-closed behavior, providing clear behavioral context.

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 a single dense block of text (over 220 words). While it contains all necessary information, it lacks structure (e.g., bullet points or separation of operation types) and could be more scannable. Some redundancy exists (e.g., 'currently referenced external atlas TSJ' is mentioned only once, which is fine). A more concise and organized structure would improve readability.

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?

Given the tool's complexity (multiple operation types, nested objects in schema, and 5 required parameters), the description covers the main behavioral aspects: what each operation does, constraints (fail-closed for certain types), and the output (expiring change set). It does not describe the output schema, but that is present separately. The description is sufficiently complete for an agent to understand the tool's purpose and usage.

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?

With 60% schema description coverage, the description compensates by explaining each operation's parameters in detail (e.g., addWangSet: name, type, optional colors up to 254 limit; setWangTiles: tileId, wangId array semantics). It clarifies critical nuance like 1-based color indexes and slot ordering, which the schema does not convey. This goes well beyond the structured input.

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 clearly states the tool validates sequential Wang edits on an external atlas TSJ, listing three specific operations (addWangSet, addWangColor, setWangTiles). It emphasizes it returns an expiring change set without modifying assets, which matches the title 'Preview Wang terrain edits' and distinguishes from sibling tools like tiled_apply_change_set.

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 implies this is a read-only preview tool ('without modifying project assets') and notes a limitation ('image-collection tilesets and pre-1.5 edgecolors/cornercolors sets fail closed'). However, it does not explicitly guide when to use this vs. alternative preview or commit tools, nor does it mention prerequisites like having a valid atlas TSJ or expected revisions.

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