MapMap

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.

Input Schema

Name	Required	Description	Default
`id`	Yes	The job id returned by `submit_optimise_job`.

Output Schema

Name	Required	Description
`id`	Yes	The job id.
`kind`	Yes	`optimise`, `replan` or `matrix`.
`error`	No	Why it failed, once `status` is `failed`.
`result`	No	The answer, inline, once `status` is `succeeded`, exactly the body the synchronous tool would have returned. 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.
`status`	Yes	`queued`, `running`, `succeeded` or `failed`. Only `succeeded` and `failed` are terminal; keep polling on the other two.
`refunded`	Yes	Whether a failure refunded the submission's units.
`terminal`	Yes	Whether `status` is one this job will never leave.
`created_at`	Yes	RFC 3339 UTC submission time.
`started_at`	No	RFC 3339 UTC time a worker picked it up.
`finished_at`	No	RFC 3339 UTC time it finished, either way.
`units_charged`	Yes	Metered units the SUBMISSION drew. This is what was charged; `refunded` says whether it came back.
`webhook_status`	No	`delivered` or `delivery_failed`, once a webhook was attempted.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 17, 2026

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."

Changed1 schema field changedSep 23, 2026

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."

AddedSep 3, 2026

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 delivers: reads are unmetered while the submission is charged, `units_charged`/`refunded` semantics on failure, and strict ownership rules where another key's id returns NOT FOUND rather than forbidden to avoid disclosing existence. These are non-obvious gateway behaviors an agent could not 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?

Purpose is front-loaded and almost every clause adds operational value, but the justification of the free-polling design ('a poll that costs quota is a poll a caller rations...') runs two clauses longer than the guidance it supports. Dense and useful, slightly discursive.

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, yet the description still explains the state machine (`queued`/`running`/`succeeded`/`failed`), the `terminal` polling signal, and the charge/refund fields in a way an agent can act on. Nothing needed to call it correctly is missing.

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% with a single required `id`, and the schema already says it comes from `submit_optimise_job`. The description adds no format, validation, or expiry detail about the id beyond that, so this is the standard 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?

States a specific verb+resource ('Read an asynchronous job submitted with `submit_optimise_job`') and names the sibling that creates such jobs. It goes further by specifying exactly what is returned (status, then result inline identical to the synchronous tool), so the agent knows the contract without opening the 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?

Explicit when and how: poll while `terminal` is false, check every few seconds rather than guessing a duration, and it names the alternative (webhooks) while excluding it for agents in a loop. This is a textbook when/when-not/alternative routing statement.

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

All MapMap 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?