DiffiCat

Wait for comparison

wait_for_comparison

Read-onlyIdempotent

Waits until the job is completed, failed or cancelled, or timeoutSeconds pass, then answers status, progress and, once terminal, the summary (passed, failed, issuesBySeverity). On "running", call it again. Free.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "jobId": "<jobId>"
    },
    "name": "wait_for_comparison"
  }
}

Input Schema

Name	Required	Description
`jobId`	Yes	Returned at job creation, e.g. web-1a2b3c.
`jobToken`	No	Returned at job creation; optional when the HTTP headers carry the key that paid the job.
`timeoutSeconds`	No	Seconds to wait for a terminal status before answering with the current one (default 60, at most 300).

Output Schema

Name	Required	Description	Default
`code`	No
`error`	No
`jobId`	No
`status`	No
`summary`	No
`progress`	No
`followUps`	No
`pagesReturned`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 7, 2026

changedInput schema / properties / jobId / description

Previous value: -"The jobId returned when the job was created, e.g. web-1a2b3c or cmp-1a2b3c."New value: +"Returned at job creation, e.g. web-1a2b3c."

changedInput schema / properties / jobToken / description

Previous value: -"The jobToken returned when the job was created. Optional when the request’s HTTP headers carry the key that paid the job."New value: +"Returned at job creation; optional when the HTTP headers carry the key that paid the job."

Changed1 schema field changedNov 2, 2026

addedOutput schema / properties / followUps

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed4 schema fields changedOct 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / jobId / description

Previous value: -"The jobId returned when the job was created, e.g. web-1a2b3c."New value: +"The jobId returned when the job was created, e.g. web-1a2b3c or cmp-1a2b3c."

changedInput schema / properties / jobId / pattern

Previous value: -"^web-[a-z0-9-]+$"New value: +"^(?:web|cmp)-[a-z0-9-]+$"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedOct 21, 2026

addedOutput schema / properties / pagesReturned

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed1 schema field changedOct 4, 2026

changedInput schema / properties / jobToken / description

Previous value: -"The jobToken returned when the job was created. Optional when the request carries the prepaid key that paid the job (Authorization: Bearer dck_…)."New value: +"The jobToken returned when the job was created. Optional when the request’s HTTP headers carry the key that paid the job."

Changed1 schema field changedSep 30, 2026
- addedInput schema / properties / jobId / description
```
Added value: +"The jobId returned when the job was created, e.g. web-1a2b3c."
```

Changed1 schema field changedSep 29, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "type": "string"
+    },
+    "error": {
+      "type": "string"
+    },
+    "jobId": {
+      "type": "string"
+    },
+    "progress": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "status": {
+      "type": "string"
+    },
+    "summary": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

AddedSep 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

The annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the description is not required to repeat them. It adds behavior they do not cover: blocking until completed, failed, or cancelled, or until timeoutSeconds elapses, and the fact that the call is free. The gaps are what happens on an expired or unknown jobId and whether a timeout counts as terminal.

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

Conciseness5/5

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

It is one dense sentence plus a two-word cost note, with the wait and timeout rule front-loaded and the polling instruction second. Nothing is redundant, and the terminal-state and summary-field details are packed efficiently.

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?

An output schema exists, so the description need not restate the return shape, and the annotations carry the safety profile. Combined with full schema coverage, the description supplies everything needed to call it correctly: the wait semantics, the terminal states, the retry rule, and the cost.

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

Parameters3/5

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

Schema coverage is 100%, so jobId, jobToken, and timeoutSeconds are already documented with defaults, bounds, and patterns. The description only implies that timeoutSeconds bounds the wait, which the schema already states. This is the expected baseline when the schema does the work.

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?

The description names a specific verb and resource: it waits on a comparison job until a terminal state or timeout, then returns status and progress. It is clearly the polling tool and can be told apart from siblings such as get_report and check_page, which fetch finished artifacts rather than block on a job.

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

Usage Guidelines4/5

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

It gives an explicit loop rule: when the status is "running", call it again. That is actionable when-to-use guidance. It does not say when to stop polling and switch to get_report, or what to do if the job never reaches a terminal state, so it stops short of a full decision rule.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?