DiffiCat

Compare against a snapshot

compare_snapshot

Free up to 40 pages a day per client address for a live compare, no key needed. Compares a saved snapshot, as Site A, against a live targetUrl (every stored page paired by path, or the urls pairs you name) at the snapshot’s width and check mode, priced at one captured page per pair (half a live pair) with no discovery; the snapshot’s own origin is never fetched. With otherSnapshotId instead of targetUrl it compares two snapshots captured alike at no charge, which needs the account’s key on the request; the compare is saved under a Pro account and otherwise removed after 30 days. Call it when the baseline was captured earlier; then wait_for_comparison and get_report as for start_comparison. dryRun: true answers the page count and price without charging. Answers with jobId, jobToken, status, pagesCharged, snapshotId or compareId and, on a free run, sample and allowanceRemaining.

Input Schema

TableJSON Schema

Name	Required	Description
`urls`	No	With targetUrl: the pairs to compare, each source a page of the snapshot (its path or full URL on the snapshot’s origin) and each target on targetUrl. Without it every stored page is paired by path.
`dryRun`	No	Quote only: runs every check and the pricing, then answers the page count and exact amount. Nothing is charged, the free allowance is not used and no job starts; the same body without dryRun is priced from the retained result.
`visual`	No	Not accepted: a run against a snapshot uses the masks and freeze recorded with the snapshot.
`targetUrl`	No	The live site to compare against the snapshot (full URL). Give this or otherSnapshotId.
`threshold`	No	Visual diff tolerance as a fraction from 0 (exact) to 1: 0.05 means 5%. The web app takes a percentage; the API does not.
`shareToken`	No	A share token (dcs_…) the snapshot’s owner issued for agents. Needed unless the account key on the request’s HTTP headers owns or was granted the snapshot.
`snapshotId`	Yes	The snapshot id, snap-<uuid>, from list_snapshots or the web app.
`callbackUrl`	No	Optional https URL (port 443) that receives one JSON POST when the job ends (jobId, status, summary, links; never the jobToken), a nudge to read the job. Public hosts only, no redirects followed, retried twice; delivery never affects the job.
`maxPriceUsd`	No	Optional spend cap in USD. A job priced above it is refused before any challenge, so an auto-paying client is never asked for more.
`idempotencyKey`	No	Optional opaque string a retry repeats: under a prepaid balance the same value within 24 hours is not charged again and answers DUPLICATE_REQUEST with the jobId of the first call.
`otherSnapshotId`	No	A second snapshot, captured at the same width and check mode, to compare the first against. Needs the account key on the request; never free. Give this or targetUrl.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`code`	No
`error`	No
`jobId`	No
`amount`	No
`dryRun`	No
`sample`	No
`status`	No
`payment`	No
`currency`	No
`jobToken`	No
`compareId`	No
`freeCovers`	No
`snapshotId`	No
`pagesPriced`	No
`pagesCharged`	No
`allowanceRemaining`	No
`pagesFromAllowance`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 16, 2026

addedInput schema / properties / visual

Added value: +{
+  "description": "Not accepted: a run against a snapshot uses the masks and freeze recorded with the snapshot."
+}

Changed1 schema field changedOct 15, 2026
- addedOutput schema / properties / freeCovers
```
Added value: +{
+  "type": "boolean"
+}
```
AddedOct 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only flag it as a non-read-only, open-world, non-idempotent, non-destructive call; the description goes far beyond that with the free allowance (40 pages/day per client address, no key), the pricing unit (one captured page per pair, half a live pair), the 'snapshot's own origin is never fetched' constraint, key requirement for snapshot-to-snapshot, and the 30-day retention rule for non-Pro accounts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence carries substantive, non-redundant information and there is no filler, but it is a dense wall of parenthetical clauses and the lead sentence is a pricing perk rather than the core purpose, so the front-loading is imperfect even if the content justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with two divergent modes, auth branching and a cost model, the description covers mode selection, key requirements, free-vs-paid behavior, dryRun semantics, follow-up jobs and even a return-shape summary. Nothing an agent needs to invoke it correctly is missing, and an output schema exists to carry return details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description still adds semantic value: dryRun returns a page count and exact price without charging, otherSnapshotId is never free and requires the account key, and pairing behavior when urls is omitted. It does not add much on threshold, shareToken or maxPriceUsd beyond the already-rich schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource and spells out both operating modes: comparing a saved snapshot as Site A against a live targetUrl, or against a second snapshot via otherSnapshotId. An agent can distinguish it from start_comparison and get_snapshot without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Call it when the baseline was captured earlier' gives the selecting condition, and 'then wait_for_comparison and get_report as for start_comparison' supplies the exact follow-up chain, routing the agent through siblings. The targetUrl-vs-otherSnapshotId branch is also stated as an explicit choice.

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

All DiffiCat tools Inspect

Try in Browser

Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?