Skip to main content
Glama

submit_optimise_job

Submit a problem too large to solve inside one request to the asynchronous lane, and get a job id back. Set kind to "optimise", "replan", "matrix" or "coverage". For the first three, pass problem in EXACTLY the shape the matching synchronous tool takes, optimise_routes input, replan_routes input, or matrix input. Moving a working synchronous call onto this lane changes nothing but which tool you call it with. A field that tool's input does not have is REFUSED by name rather than dropped: the HTTP API accepts some the MCP tools have not surfaced yet, and a job queued without a constraint you asked for is worse than one that was never queued. "coverage" plans one drive that passes along EVERY street in an area at least once, in the legal direction, split into outings (the Chinese postman problem on the real road network): survey capture, street sweeping, gritting, refuse rounds. It has no synchronous tool; its problem is the POST /v1/jobs/coverage body: exactly one of bbox ([min_lon, min_lat, max_lon, max_lat]) or polygon (GeoJSON), and optionally costing ("auto" or "truck"), optimise ("distance", "time" or "balanced"), road_classes {include, exclude}, include_private, turn_penalties {avoid_left, avoid_right, avoid_u_turn} in metres per turn, chunk_km (outing length, default 15; outings land as close to it as the streets allow) or instead chunk_time_s (outing time, 900 to 21,600 s; both is refused: each outing's trip_time_s, with chunk_loops its transfers included), chunk_tolerance (default 0.25, 0.05 to 0.5: the band either way of the target an outing counts as on target), time_factor (0.5 to 3, default 1: multiplies every time, a pace correction for a vehicle slower than the graph's speeds), start {lat, lon, heading?, snap?}, return_to_start, boundary, max_outside_m, chunk_loops, loop_radius_m, exclude, avoid and required. start snaps to the nearest junction the plan passes; with snap: "exact" the drive starts where the car is (on the street within 50 m, facing heading if given, never turning round in the street) and the drive from there to the plan is planned too: outing 1's first steps, or with chunk_loops its transfer_from_previous (summary.approach_km). return_to_start: false ends the plan wherever leaves the least driving. boundary ("touching" default, "mostly_inside", "inside") decides which streets crossing the area's edge must be covered. max_outside_m (0 to 2,000 m) holds the drive within that distance of the area's edge: streets crossing the edge that reach further out are not covered, and divided roads turn round inside the limit where they can; summary.outside_area lists every stretch of the drive outside the area, how far it goes and, with the limit, which go past it because nothing within it joins up. chunk_loops: true makes every outing a closed loop that starts and ends at the same junction, with the drive between outings planned as a separate route (each chunk's transfer_from_previous, plus transfer_to_start with return_to_start); walk_km excludes those transfers (summary.transfer_km has them), and summary.outings_outside_target names any outing outside the target x (1 +/- chunk_tolerance) and why; summary.outing_km and summary.outing_time_s give the median, p10, p90, min and max outing km and trip time and how many are within 10 % and within the tolerance. Drive times include the engine's own junction time (turns, U-turns, signals). loop_radius_m (0 to 2,000 m, only with chunk_loops) lets an outing end within that distance of its start when that saves driving; loop_end: "last_covered" (only with chunk_loops) ends an outing where its last covered street does instead of driving back over covered streets, when the drive on is then shorter; chunk_measure: "trip" (only with chunk_loops, not with chunk_time_s) aims chunk_km at each outing's trip_km (the outing and its transfers) instead of its own km; chunk_grouping: "compact" (only with chunk_loops) builds each outing from adjacent streets, one compact part of the area each, so outings cross one another's streets less (each chunk's hull_km2 and summary.outing_overlap_share show it). exclude.way_ids lists OpenStreetMap way ids not to cover, taken from the way_id of a previous plan's steps; exclude.areas is a GeoJSON polygon, and a street more than half inside it is not covered. An excluded street may still be driven to connect others, as a deadhead step. Ids that no longer match the graph are listed back in the result's summary.exclude_unmatched_way_ids. avoid is a hard block, never driven, not even to connect streets or between outings: avoid.way_ids closes whole ways both ways; avoid.locations (at most 2,000) [{lat, lon, radius_m?, heading? or headings? (1 to 4), heading_tolerance?, way_id?}] closes the street a point is on (never the cross street; within 3 m of a junction it needs heading or way_id, else it closes nothing and comes back in summary.avoid_unmatched), one direction with heading (the heading /locate reports at the point matches, on a bend and near a junction of the same way too), each direction of headings, only that way's street with way_id, or every street within radius_m (0 to 100); summary.avoid_matched lists the edges each place closed (edge_id, way_id, direction). avoid.close_from_point: true closes a street from the point rather than the whole edge: the street up to the point is kept and driven as a dead end that turns round avoid.stop_short_m (1 to 50, default 5) short of it (summary.avoid_matched[].kept, chunks[].turn_rounds; guidance makes that turn a U-turn). exclude.uses (e.g. ["parking_aisle", "driveway"]) leaves road uses uncovered but drivable; skip_dead_ends_m (1 to 500) leaves dead ends shorter than that from their junction uncovered, listed in summary.skipped_dead_ends. Streets to cover that a block closes or cuts off are listed in summary.dropped_ways with a reason (avoided, unreachable_after_avoid, no_legal_loop) and their edges (edge_id, length_m, polyline6 geometry). summary.u_turns lists each U-turn of the plan with where it is and why it stays. required {way_ids?, segments?: [{way_id, from_m, to_m}]} covers only those ways or ranges (metres from the way's first node, in its own OSM direction), driving the rest of the area only to connect them; it never widens boundary, road_classes or exclude, ranges are covered junction to junction, and summary.required_coverage / summary.required_unmatched say what each range covers and what requires nothing, with why (a ring such as a roundabout has no first node: name it in way_ids). After planning, every turn the graph forbids and every U-turn where a street merely continues, on a bridge or on a tertiary or bigger road is replaced by the cheapest legal way round (deadhead); other U-turns not at a dead end are replaced when that costs less than avoid_u_turn, alone or two at a time where a short drive joins them (summary.turns.u_turns_paired counts those). The result (from get_job) has chunks (the outings) with ordered steps (way_id, name, deadhead) and a ready trace_route body each, plus trace_route_parts, the same replay cut into pieces that never pass a junction twice (the engine's exact edge walk can refuse a drive that comes back through a junction as one piece; the pieces it walks). A client turns one outing or transfer into turn-by-turn guidance with one call to the HTTP API's POST /v1/coverage/guidance (job id and outing id): one trip, one leg per piece, never map matched. And a summary including dropped and excluded streets and restricted_turns (only the restricted turns and refused U-turns no legal way round could replace, with where and why; summary.turns counts the ones replaced and the km they added). Billed per started square kilometre: charged on the area's bounding box, settled on success to the polygon's own area or its street floor, whichever is larger (the result's billing); the gateway's area, edge and time limits apply. A drive in progress that meets a closed street is re-planned from where the car is with one call to the HTTP API's POST /v1/coverage/reroute (job id, outing id, the car's position and heading, and avoid): the rest of the outing round the closure as a chunk ready for guidance, with the covering steps it leaves out. The ceilings are far higher here because there is no request to hold open: 2,000 unique locations for an optimisation or re-plan against the synchronous 200, and 40,000 matrix elements against 10,000 (a deployment may set either lower, in which case its own refusal is the authority). A re-plan is counted on the REMAINING problem, after completed stops are removed, so a shift well through its day may fit where the morning's would not. This answers 202-and-a-job-id, NOT a plan: the job is queued and a worker picks it up. Poll get_job with the returned id until it says the status is terminal, then read the result. Polling is free, the gateway meters this submission, not the reads. Units are charged on submission and handed back in full if the job fails. The optional webhook_url (https only) posts a SIGNED notification when the job finishes and is for a human wiring infrastructure that must react without a process watching; it carries a pointer, never the result, and needs a webhook signing secret on the key. An agent that can poll should not use it. 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": {
      "kind": "<kind>",
      "problem": "<problem>"
    },
    "name": "submit_optimise_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYesWhich problem this is. It selects both the body shape below and the ceiling the submission is judged against.
problemYesThe problem itself, in exactly the shape the synchronous tool takes , `optimise_routes` input for `optimise`, `replan_routes` input for `replan`, `matrix` input for `matrix`. Moving a working synchronous call onto this lane changes nothing but the tool you call it with. `coverage` has no synchronous tool: its problem is the `POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`, `optimise`, `road_classes`, `include_private`, `turn_penalties`, `chunk_km`, `chunk_tolerance`, `start`, `return_to_start`, `chunk_loops`, `loop_radius_m`, `exclude`, `avoid`, `required`), without `webhook_url`, which is this tool's own field.
webhook_urlNoOptional HTTPS URL to POST a signed `{job_id, kind, status, result_url}` notification to when the job finishes. The RESULT is never pushed, the notification says where to fetch it. Requires a webhook signing secret on the key; without one the submission is refused rather than delivered unsigned. An agent that can poll does not need this: polling with `get_job` is free.

Output Schema

NameRequiredDescriptionDefault
idYesThe job id. Pass it to `get_job` to poll.
kindYes`optimise`, `replan`, `matrix` or `coverage`.
nextYesWhat to do next, in one sentence: poll `get_job`, and how often is reasonable.
statusYesAlways `queued`, no worker has looked at it yet.
result_urlYesThe HTTP URL this job (and its result) can be fetched from. The same URL a webhook carries. `get_job` is the tool that reads it.
units_chargedYesQuota units this submission drew. Charged now, handed back in full if the job fails.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `chunk_tolerance`, `start`, `return_to_start`,\n`chunk_loops`, `loop_radius_m`, `exclude`, `avoid`), without\n`webhook_url`, which is this tool's own field."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `chunk_tolerance`, `start`, `return_to_start`,\n`chunk_loops`, `loop_radius_m`, `exclude`, `avoid`, `required`), without\n`webhook_url`, which is this tool's own field."
  2. Changed1 schema field changed
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `chunk_loops`,\n`loop_radius_m`, `exclude`, `avoid`), without\n`webhook_url`, which is this tool's own field."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `chunk_tolerance`, `start`, `return_to_start`,\n`chunk_loops`, `loop_radius_m`, `exclude`, `avoid`), without\n`webhook_url`, which is this tool's own field."
  3. Changed1 schema field changed
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `chunk_loops`,\n`loop_radius_m`, `exclude`), without\n`webhook_url`, which is this tool's own field."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `chunk_loops`,\n`loop_radius_m`, `exclude`, `avoid`), without\n`webhook_url`, which is this tool's own field."
  4. Changed1 schema field changed
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `exclude`), without\n`webhook_url`, which is this tool's own field."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `chunk_loops`,\n`loop_radius_m`, `exclude`), without\n`webhook_url`, which is this tool's own field."
  5. Changed3 schema fields changed
    • changedInput schema / $defs / JobKind / oneOf
      Previous value: -[
      -  {
      -    "const": "optimise",
      -    "description": "A fleet optimisation, the `optimise_routes` problem, at ten times\nthe synchronous location cap.",
      -    "type": "string"
      -  },
      -  {
      -    "const": "replan",
      -    "description": "A mid-shift re-plan, the `replan_routes` problem, counted on the\nremaining work.",
      -    "type": "string"
      -  },
      -  {
      -    "const": "matrix",
      -    "description": "A many-to-many time/distance matrix, the `matrix` problem, at four\ntimes the synchronous element cap.",
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "const": "optimise",
      +    "description": "A fleet optimisation, the `optimise_routes` problem, at ten times\nthe synchronous location cap.",
      +    "type": "string"
      +  },
      +  {
      +    "const": "replan",
      +    "description": "A mid-shift re-plan, the `replan_routes` problem, counted on the\nremaining work.",
      +    "type": "string"
      +  },
      +  {
      +    "const": "matrix",
      +    "description": "A many-to-many time/distance matrix, the `matrix` problem, at four\ntimes the synchronous element cap.",
      +    "type": "string"
      +  },
      +  {
      +    "const": "coverage",
      +    "description": "A drive-every-street plan (the Chinese postman problem on the road\nnetwork): one drive along every street in an area, split into\noutings. There is no synchronous tool for it, so `problem` is the\n`POST /v1/jobs/coverage` body itself, see [`CoverageProblem`].",
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `start`, `return_to_start`, `exclude`), without\n`webhook_url`, which is this tool's own field."
    • changedOutput schema / properties / kind / description
      Previous value: -"`optimise`, `replan` or `matrix`."New value: +"`optimise`, `replan`, `matrix` or `coverage`."
  6. Changed4 schema fields changed
    • changedInput schema / $defs / JobKind / oneOf
      Previous value: -[
      -  {
      -    "const": "optimise",
      -    "description": "A fleet optimisation — the `optimise_routes` problem, at ten times\nthe synchronous location cap.",
      -    "type": "string"
      -  },
      -  {
      -    "const": "replan",
      -    "description": "A mid-shift re-plan — the `replan_routes` problem, counted on the\nremaining work.",
      -    "type": "string"
      -  },
      -  {
      -    "const": "matrix",
      -    "description": "A many-to-many time/distance matrix — the `matrix` problem, at four\ntimes the synchronous element cap.",
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "const": "optimise",
      +    "description": "A fleet optimisation, the `optimise_routes` problem, at ten times\nthe synchronous location cap.",
      +    "type": "string"
      +  },
      +  {
      +    "const": "replan",
      +    "description": "A mid-shift re-plan, the `replan_routes` problem, counted on the\nremaining work.",
      +    "type": "string"
      +  },
      +  {
      +    "const": "matrix",
      +    "description": "A many-to-many time/distance matrix, the `matrix` problem, at four\ntimes the synchronous element cap.",
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / problem / description
      Previous value: -"The problem itself, in exactly the shape the synchronous tool takes\n— `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with."New value: +"The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with."
    • changedInput schema / properties / webhook_url / description
      Previous value: -"Optional HTTPS URL to POST a signed `{job_id, kind, status,\nresult_url}` notification to when the job finishes. The RESULT is\nnever pushed — the notification says where to fetch it. Requires a\nwebhook signing secret on the key; without one the submission is\nrefused rather than delivered unsigned. An agent that can poll does\nnot need this: polling with `get_job` is free."New value: +"Optional HTTPS URL to POST a signed `{job_id, kind, status,\nresult_url}` notification to when the job finishes. The RESULT is\nnever pushed, the notification says where to fetch it. Requires a\nwebhook signing secret on the key; without one the submission is\nrefused rather than delivered unsigned. An agent that can poll does\nnot need this: polling with `get_job` is free."
    • changedOutput schema / properties / status / description
      Previous value: -"Always `queued` — no worker has looked at it yet."New value: +"Always `queued`, no worker has looked at it yet."
  7. Added

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so: it discloses that the call returns 202 plus a job id rather than a plan, that a worker picks it up asynchronously, that polling is free while the submission is metered, that units are charged on submission and refunded in full on failure, that billing is per started square kilometre settled to the larger of polygon area or street floor, and that the gateway and its area/edge/time limits apply. `webhook_url` behaviour (HTTPS only, signed, pointer-not-result, requires a signing secret, refused without one) is stated rather than left to inference.

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

Conciseness2/5

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

For a three-parameter submission tool this is an enormous single block paragraph, most of it a reference manual for the `coverage` problem body, `chunk_loops`, `avoid` geometry rules, `required` ranges and downstream guidance/reroute HTTP endpoints. The first sentence is well front-loaded, but the bulk is specification material that belongs with the coverage tool or the API docs, and an agent must wade through it to find the submission-relevant facts.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/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 explained, yet the description still sketches the `chunks`/`steps`/`summary`/`billing` result honestly. Nothing an agent needs to submit or poll correctly is missing; the only cost is that completeness is achieved by bulk rather than by targeting the async-submission concern.

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 `kind`, `problem` and `webhook_url` are already documented; the baseline would be 3. The description nonetheless adds real meaning: it pins `problem` to the exact input shape of the matching synchronous tool and explains why unknown fields are refused by name, and it enumerates the coverage body's options and defaults (chunk_km, chunk_tolerance, time_factor, boundary, avoid/required semantics) well beyond the schema's field listing.

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 sentence names a specific action and result: submit an oversized problem to the asynchronous lane and get a job id back. It explicitly distinguishes itself from `optimise_routes`, `replan_routes` and `matrix` (the synchronous equivalents) and notes that `coverage` has no synchronous counterpart, so an agent can route between lanes without opening a 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 states the selection condition plainly ('too large to solve inside one request'), says moving an existing synchronous call onto this lane is otherwise a no-op, and gives the concrete ceilings that separate the lanes (2,000 locations vs 200; 40,000 matrix elements vs 10,000). It also tells the agent what to do next -- poll `get_job` until terminal -- and explicitly says an agent that can poll should not use `webhook_url`.

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