PollJob

Poll the status of an async job and retrieve results when complete. The agent decides when and how often to poll — the tool never blocks.

When to Use

Check the status of a running comparison or parse job
Retrieve the list of generated overlays after a comparison completes
Report progress to the user while a job is processing
Short-poll with wait_seconds to reduce round-trips

Parameters

Parameter	Type	Required	Description
`job_id`	string	yes	Job ID returned by `Compare` or `Parse`
`wait_seconds`	number	no	Short-poll: wait up to this many seconds for a status change (max 15). Reduces round-trips for fast jobs.

Response

In Progress

{
  "id": "job_cmp_01",
  "status": "started",
  "progress": {
    "completed": 3,
    "total": 8
  }
}

Field	Type	Description
`id`	string	Job ID
`status`	string	`"queued"`, `"started"`, or `"completed"`
`progress.completed`	number	Number of sheet pairs processed so far
`progress.total`	number	Total sheet pairs to process

Completed

{
  "id": "job_cmp_01",
  "status": "completed",
  "progress": {
    "completed": 8,
    "total": 8
  },
  "result": {
    "overlays": [
      {
        "id": "ov_01",
        "block_a": {
          "type": "Plan",
          "sheet_number": "A-101",
          "drawing_name": "Arch Set Rev A"
        },
        "block_b": {
          "type": "Plan",
          "sheet_number": "A-101",
          "drawing_name": "Arch Set Rev B"
        },
        "score": 0.82,
        "uri": "storage://overlays/ov_01/composite.png"
      }
    ]
  }
}

The score indicates how similar the two blocks are (0.0 = completely different, 1.0 = identical). Lower scores mean more changes. After completion, use Query with entity: "block" and include: ["overlays", "changes"] on either block to get detailed change and clash descriptions.

Failed

{
  "id": "job_cmp_01",
  "status": "failed",
  "error": {
    "code": "job_failed",
    "message": "Comparison failed: no matching sheets found between drawings"
  }
}

Examples

Poll a running comparison

{
  "job_id": "job_cmp_01"
}

If the job is still running, the agent can report progress to the user: “3 of 8 sheet pairs processed. Checking again…”

Retrieve completed results

{
  "job_id": "job_cmp_01"
}

When status is "completed", the result.overlays array lists every matched block pair with its similarity score. The agent can sort by score to identify sheets with the most changes and drill into them first.

A good polling pattern: wait 2-3 seconds after triggering Compare, then poll. For large drawing sets, the agent can tell the user “Processing 12 sheet pairs, this may take a minute” and poll at longer intervals.

Compare - Trigger a comparison job
Parse - Trigger a parse job
Query - Fetch detailed changes, clashes, or extracted features after the job completes
ViewImage - View overlay images referenced in the results

Overview

Tools

Workflows

Reference

When to Use

Parameters

Response

In Progress

Completed

Failed

Examples

Poll a running comparison

Retrieve completed results

​When to Use

​Parameters

​Response

​In Progress

​Completed

​Failed

​Examples

​Poll a running comparison

​Retrieve completed results

​Related Tools

When to Use

Parameters

Response

In Progress

Completed

Failed

Examples

Poll a running comparison

Retrieve completed results

Related Tools