Compare FigCraft Design and Web UI

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

With no annotations, the description carries the burden well: it discloses that the heatmap write is optional, that it is destructive-safe ('only when explicitly true' via overwrite), and what metrics are returned. It does not explain failure behavior when image dimensions mismatch or what happens when diffPath exists and overwrite is false.

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?

Two compact sentences pack purpose, output contract, optional side effect, and scope exclusion with no filler. The exclusion clause is placed last where it functions as a disambiguator without burying 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?

No output schema exists, and the description compensates by naming every returned metric, which is the critical gap-filler. For a six-parameter mutation-capable tool with no annotations, error/precondition handling (size mismatch, existing file) is the only notable omission.

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 100%, so all six parameters are already documented with defaults and ranges; the description reinforces the same ground (diff heatmap, threshold pass/fail, same-size requirement). It adds the semantic framing of the diff output but no parameter detail beyond the schema, so baseline 3 is appropriate.

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?

States a specific verb and resource ('Compare two same-size PNG screenshots') and enumerates exactly what is produced: diff percentage, mean absolute error, changed bounding box, threshold pass/fail. The closing 'not semantic UX analysis' draws a bright line against siblings like review_ui and audit_ui_page.

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 exclusion of semantic UX analysis implicitly routes pixel-level verification here and judgment-based review to review_ui/audit_ui_page. The 'same-size' precondition is stated, but no explicit when-to-use guidance or reference to capture_ui_screenshots as the upstream step.

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