Skip to main content
Glama

get_job

Read an asynchronous job submitted with submit_optimise_job: its status, and once it has finished, its result inline, exactly the body the synchronous tool would have returned. Status is queued, running, succeeded or failed; the answer's terminal field says whether the job will ever leave the status it is in, so poll while that is false. POLLING IS FREE: the gateway meters the submission and not the reads, deliberately, because a poll that costs quota is a poll a caller rations, and a rationed poll is how a job that finished in ten seconds gets noticed four minutes later. Check every few seconds rather than guessing at a duration. units_charged is what the SUBMISSION drew, and refunded says whether a failure handed it back, a failed job shows both, because reporting zero would be a lie about what was charged. Webhooks are the alternative to polling and exist for humans wiring infrastructure, not for agents in a loop. A job belongs to the key that submitted it (or another key of the same identity); anyone else's id answers NOT FOUND rather than forbidden, because confirming an id exists is itself a disclosure. Requires the MapMap gateway.

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": {
      "id": "<id>"
    },
    "name": "get_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe job id returned by `submit_optimise_job`.

Output Schema

NameRequiredDescriptionDefault
idYesThe job id.
kindYes`optimise`, `replan`, `matrix` or `coverage`.
errorNoWhy it failed, once `status` is `failed`.
resultNoThe answer, inline, once `status` is `succeeded`, exactly the body the synchronous tool would have returned (for `coverage`, which has none, the gateway's plan unchanged). A matrix job answers `durations_s` and `distances_m`, as the `matrix` tool does; it also still carries the same numbers as `durations` and `distances`, which are DEPRECATED and will be removed in a future release.
statusYes`queued`, `running`, `succeeded` or `failed`. Only `succeeded` and `failed` are terminal; keep polling on the other two.
refundedYesWhether a failure refunded the submission's units.
terminalYesWhether `status` is one this job will never leave.
created_atYesRFC 3339 UTC submission time.
started_atNoRFC 3339 UTC time a worker picked it up.
finished_atNoRFC 3339 UTC time it finished, either way.
units_chargedYesMetered units the SUBMISSION drew. This is what was charged; `refunded` says whether it came back.
webhook_statusNo`delivered` or `delivery_failed`, once a webhook was attempted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / kind / description
      Previous value: -"`optimise`, `replan` or `matrix`."New value: +"`optimise`, `replan`, `matrix` or `coverage`."
    • changedOutput schema / properties / result / description
      Previous value: -"The answer, inline, once `status` is `succeeded`, exactly the body\nthe synchronous tool would have returned. A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."New value: +"The answer, inline, once `status` is `succeeded`, exactly the body\nthe synchronous tool would have returned (for `coverage`, which has\nnone, the gateway's plan unchanged). A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."
  2. Changed1 schema field changed
    • changedOutput schema / properties / result / description
      Previous value: -"The answer, inline, once `status` is `succeeded` — exactly the body\nthe synchronous tool would have returned. A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."New value: +"The answer, inline, once `status` is `succeeded`, exactly the body\nthe synchronous tool would have returned. A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."
  3. Changed1 schema field changed
    • changedOutput schema / properties / result / description
      Previous value: -"The answer, inline, once `status` is `succeeded` — exactly the body\nthe synchronous tool would have returned."New value: +"The answer, inline, once `status` is `succeeded` — exactly the body\nthe synchronous tool would have returned. A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."
  4. Added

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the four status values, the `terminal` sentinel, that reads are unmetered while the submission is charged, how `units_charged`/`refunded` behave on failure, ownership scoping by key, and the deliberate NOT-FOUND-rather-than-forbidden disclosure policy. These are non-obvious behaviors an agent cannot infer from the schema.

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?

Front-loaded with the purpose, then the polling rule, then edge behaviors, which is the right ordering. It is somewhat long-winded, though: the 'POLLING IS FREE... a rationed poll is how a job that finished in ten seconds gets noticed four minutes later' sentence is rhetorical padding whose operational content ('reads don't consume quota, poll every few seconds') could be stated in one clause.

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 no explanation, and the description still surfaces the fields that affect agent decisions (`terminal`, `units_charged`, `refunded`). Ownership, failure, and polling cadence are all covered, leaving nothing an agent needs in order to call it correctly.

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% and the single `id` parameter is already documented as coming from `submit_optimise_job`, so the description adds no syntax or format detail beyond the schema. The one added nuance, that another identity's id returns NOT FOUND, is behavioral rather than parameter semantics. Baseline 3 applies.

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?

States a specific verb and resource ('Read an asynchronous job submitted with `submit_optimise_job`') and immediately names the paired sibling tool, so an agent can distinguish it from `submit_optimise_job` and `get_usage` without opening a schema. It also pins down what is returned (status, then the inline result body).

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?

Explicitly says when to poll ('poll while that is false', 'check every few seconds rather than guessing at a duration') and names the alternative (webhooks) with a clear exclusion: 'for humans wiring infrastructure, not for agents in a loop'. That is a complete when/when-not/alternative decision rule.

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.

Resources