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
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Which problem this is. It selects both the body shape below and the ceiling the submission is judged against. | |
| problem | Yes | The 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_url | No | Optional 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
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The job id. Pass it to `get_job` to poll. | |
| kind | Yes | `optimise`, `replan`, `matrix` or `coverage`. | |
| next | Yes | What to do next, in one sentence: poll `get_job`, and how often is reasonable. | |
| status | Yes | Always `queued`, no worker has looked at it yet. | |
| result_url | Yes | The 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_charged | Yes | Quota units this submission drew. Charged now, handed back in full if the job fails. |