Render a visual map diff

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

The description adds significant behavioral details beyond annotations: it explains the visual output format (differing pixels red, matching faded, tile-cell aggregation), the requirement for matching pixel sizes, and the ability to compare with different layer selections. The 'Read-only' tag reinforces the annotations.

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 four sentences and front-loads the main purpose. It is relatively concise with no obvious filler, though the first sentence is somewhat long.

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 has a good output schema and annotations covering safety, the description provides enough behavioral context (visual output, constraints) for an agent to use the tool. It lacks parameter details but is adequate overall.

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 description coverage is only 33% (mapPathA and mapPathB have descriptions). The tool description does not add specific meaning for parameters like region, scale, or layerIdsA/B, which are left without explanation. With low schema coverage, the description should compensate but fails to do so.

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 it renders a visual diff of two maps, comparing them pixel by pixel. It specifies the diff representation (red for differing, faded for matching) and distinguishes itself from sibling render tools like tiled_render_preview by being specifically for comparison.

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 gives context on when to use (comparing two maps or same map with different layers) and a constraint (pixel size agreement). However, it does not explicitly state when not to use or compare to alternatives like tiled_render_preview.

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