Skip to main content
Glama

Follow a long-running job

get_job
Read-onlyIdempotent

Check on a crawl, run, batch or web search a tool handed back as a job, and return its result once finished. Call it when a tool answered with status 'running' and a job; repeating that tool is not needed. To stop a crawl, run or batch use cancel_job. For a project's stored pages use list_pages. Inputs: kind, id and project_id come from the 'job' object; a crawl_site crawl_id is a crawl's id. For a crawl, url reads one page in full, even mid-crawl, and cursor from the last answer reads the next window. Behaviour: it answers at once and never waits, so call it again every 10 to 30 seconds while the status is 'running'. A finished crawl answers as crawl_site does (up to 50 pages excerpted per window), a batch as scrape_urls, a search as search_web, a run with its record. A scraping search whose pages are still landing answers with its results and the job. A crawl expires a day after it started unless kept, then answers 404. Read-only and free: it reads stored data and never fetches.

Input Schema

NameRequiredDescriptionDefault
idYesThe job's id.
urlNoCrawls only: one page's URL from the crawl's index.
kindYes'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (search_web).
cursorNoCrawls only: the cursor the previous answer returned.
project_idNoA run's project id; required for a run, ignored otherwise.

Output Schema

NameRequiredDescriptionDefault
idNoA run or a search: its id.
jobNoWhile running: {kind, id, project_id} to call again with.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
noteNoWhat to do next.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
indexNoA finished crawl or batch: every page as {url, title, words, status}.
pagesNoA finished crawl or batch: pages with excerpts.
countsNoPages by outcome so far.
cursorNoA crawl with more pages: pass it back for the next window.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
statusNo'running' while it goes on; otherwise the finished job's status. On an error, the HTTP status code.
resultsNoA search: the ranked results, as search_web returns them, with page excerpts when it scraped.
crawl_idNoA crawl: its id.
markdownNoWith url: that page's markdown, capped at 12,000 characters.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (web_search)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (search_web)."
    • changedOutput schema / description
      Previous value: -"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search web_search's, a run the run record, and `url` one page in full."New value: +"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search search_web's, a run the run record, and `url` one page in full."
    • changedOutput schema / properties / results / description
      Previous value: -"A search: the ranked results, as web_search returns them, with page excerpts when it scraped."New value: +"A search: the ranked results, as search_web returns them, with page excerpts when it scraped."
  2. Changed5 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run) or 'batch' (scrape_urls with several URLs)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (web_search)."
    • changedInput schema / properties / kind / enum
      Previous value: -[
      -  "crawl",
      -  "run",
      -  "batch"
      -]New value: +[
      +  "crawl",
      +  "run",
      +  "batch",
      +  "search"
      +]
    • changedOutput schema / description
      Previous value: -"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na run the run record, and `url` one page in full."New value: +"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search web_search's, a run the run record, and `url` one page in full."
    • changedOutput schema / properties / id / description
      Previous value: -"A run: its id."New value: +"A run or a search: its id."
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "A search: the ranked results, as web_search returns them, with page excerpts when it scraped.",
      +  "title": "Results"
      +}
  3. Changed6 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Crawls only: the cursor a previous crawl answer returned, to read the next window of pages."New value: +"Crawls only: the cursor the previous answer returned."
    • changedInput schema / properties / id / description
      Previous value: -"The job's id, from that 'job' object, or a crawl_site answer's crawl_id."New value: +"The job's id."
    • changedInput schema / properties / kind / description
      Previous value: -"What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or 'batch' (scrape_urls); the 'job' object a tool returned names it."New value: +"'crawl' (crawl_site), 'run' (start_run) or 'batch' (scrape_urls with several URLs)."
    • changedInput schema / properties / project_id / description
      Previous value: -"Required for a run: the project it belongs to (the 'job' object carries it). Ignored for a crawl or a batch."New value: +"A run's project id; required for a run, ignored otherwise."
    • changedInput schema / properties / url / description
      Previous value: -"Crawls only: one page's URL from the crawl's index, to read that page in full."New value: +"Crawls only: one page's URL from the crawl's index."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na run the run record, and `url` one page in full.",
      +  "properties": {
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "counts": {
      +      "description": "Pages by outcome so far.",
      +      "title": "Counts"
      +    },
      +    "crawl_id": {
      +      "description": "A crawl: its id.",
      +      "title": "Crawl Id"
      +    },
      +    "cursor": {
      +      "description": "A crawl with more pages: pass it back for the next window.",
      +      "title": "Cursor"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "id": {
      +      "description": "A run: its id.",
      +      "title": "Id"
      +    },
      +    "index": {
      +      "description": "A finished crawl or batch: every page as {url, title, words, status}.",
      +      "title": "Index"
      +    },
      +    "job": {
      +      "description": "While running: {kind, id, project_id} to call again with.",
      +      "title": "Job"
      +    },
      +    "markdown": {
      +      "description": "With url: that page's markdown, capped at 12,000 characters.",
      +      "title": "Markdown"
      +    },
      +    "note": {
      +      "description": "What to do next.",
      +      "title": "Note"
      +    },
      +    "pages": {
      +      "description": "A finished crawl or batch: pages with excerpts.",
      +      "title": "Pages"
      +    },
      +    "status": {
      +      "description": "'running' while it goes on; otherwise the finished job's status. On an error, the HTTP status code.",
      +      "title": "Status"
      +    }
      +  },
      +  "title": "JobOut",
      +  "type": "object"
      +}
  4. Changed6 schema fields changed
    • addedInput schema / properties / cursor / description
      Added value: +"Crawls only: the cursor a previous crawl answer returned, to read the next window of pages."
    • addedInput schema / properties / id / description
      Added value: +"The job's id, from that 'job' object, or a crawl_site answer's crawl_id."
    • addedInput schema / properties / kind / description
      Added value: +"What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or 'batch' (scrape_urls); the 'job' object a tool returned names it."
    • addedInput schema / properties / kind / enum
      Added value: +[
      +  "crawl",
      +  "run",
      +  "batch"
      +]
    • addedInput schema / properties / project_id / description
      Added value: +"Required for a run: the project it belongs to (the 'job' object carries it). Ignored for a crawl or a batch."
    • addedInput schema / properties / url / description
      Added value: +"Crawls only: one page's URL from the crawl's index, to read that page in full."
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive, non-open-world), it discloses behavior the annotations cannot: it answers immediately and never waits, should be re-called every 10-30s while running, output shape mirrors the originating tool, partial search results are returned mid-flight, and crawls expire after a day returning 404. These are the details an agent actually needs to poll correctly.

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?

Well front-loaded (purpose, then trigger, then Inputs/Behaviour/read-only labels), and every sentence carries information. It is on the longer side and the 'answers as X does' sentence is dense, but nothing is filler.

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 return values need not be described, and the annotations cover the safety profile. The description nevertheless covers triggering, polling cadence, partial results, expiry and parameter sourcing, leaving no gap an agent would need to guess at.

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 coverage is 100%, so each parameter is already documented. The description still adds non-duplicative value: it explains that kind/id/project_id are read from the 'job' object, that crawl_site's crawl_id maps to `id`, and how url/cursor select a page and window. Minor edge cases (e.g. enum semantics) remain in the schema.

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 opening states a specific verb (check on / return result) and resource (a job handed back by crawl, run, batch or web search), and immediately distinguishes itself from siblings by naming cancel_job and list_pages. An agent can tell what this does without opening any 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?

It gives an explicit trigger ('when a tool answered with status running and a job') and an explicit non-action ('repeating that tool is not needed'), then routes to alternatives by condition: cancel_job to stop, list_pages for stored pages. This is exactly when/when-not/alternatives guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.