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

With no annotations provided, the description carries the full burden and delivers richly. It discloses that the tool returns both a similarity score and changed-pixel count as text, AND returns baseline/live/diff images for direct viewing, explicitly framing the tool as a decision-support aid rather than an automated judge. It also discloses the input format constraints (raw base64, no 'data:' prefix).

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 paragraph that front-loads the core purpose and then layers on usage guidance, return-value detail, and parameter alternatives. It's comprehensive and each sentence earns its place, though it is somewhat long and could benefit from light structuring for scannability.

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 having no output schema and no annotations, the description is self-sufficient. It explains return formats (text score/count plus three viewable images), the judgment framing (regression vs noise with concrete examples), and both input paths. For a 4-parameter tool with 1 required param, this is complete; the return-value explanation compensates for the missing output 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?

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the relationship between review_id and baseline_image_base64 (mutually exclusive alternatives), clarifying when to use each, and providing meaning to the label param ('for log correlation only'), beyond what the schema offers.

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 'Compare two screenshots... using a perceptual pixel-diff' with a specific verb and resource. It distinctly separates itself from sibling tools like list_visual_reviews and get_visual_review by specifying it performs the actual comparison and returns images for human judgment, and references review_id from list_visual_reviews as a distinct workflow.

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 explicitly explains when to use this tool (to judge whether flagged differences are real regressions vs benign noise), and clarifies what it does NOT do ('this tool does not make that call for you'). It also provides clear alternatives for obtaining baselines: supply two base64 images directly OR use review_id from list_visual_reviews.

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