set_map_tiles

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states that cells outside the map are skipped and that 0 clears a cell, which are important edge-case behaviors. However, it does not mention that existing tiles are overwritten (though 'stamp' implies this) or any irreversibility/side effects, so it is not maximally transparent.

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?

Three sentences, no filler, each sentence contributes essential information: the operation, grid semantics, out-of-bounds behavior, and a preview pointer. It is well-structured and front-loaded with the primary action.

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 moderate complexity (5 params, no output schema), the description covers the core mechanics of stamping, the meaning of grid values, out-of-bounds handling, and a preview method. It does not explain the return value, but for a mutation tool that is not essential. It is nearly complete, though it could mention whether the stamp overwrites or merges.

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?

Schema coverage is 80% (mapId lacks a description), but the description adds clarifying semantics: 'grid is rows of ids (0 clears a cell)' goes beyond the schema's generic '2D array of tile ids (rows)', and 'top-left at (x, y)' clarifies the positional parameters. This adds value beyond the input schema.

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 ('Stamp'), names the exact resource (a 2D block of tile ids into a layer), and specifies the positioning (top-left at (x, y)). This clearly distinguishes it from sibling tools like fill_region or scatter_tiles, which have different operations.

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 usage for placing rectangular blocks of tiles and suggests previewing with render_map, but it does not explicitly state when to choose this tool over alternatives like fill_region or scatter_tiles. No exclusions or alternative comparisons are provided.

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