Skip to main content
Glama

MapMap

by ai.mapmap

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" or "matrix", and 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. 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.

Input Schema

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

TableJSON Schema
NameRequiredDescriptionDefault
idYesThe job id. Pass it to `get_job` to poll.
kindYes`optimise`, `replan` or `matrix`.
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. Dates show when Glama detected each change.

  1. Added

TDQS

A5/5.0
Behavior5/5

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

With no annotations, the description fully carries the burden and does so richly. It discloses that the tool returns a 202-and-job-id, not a plan; that jobs are queued and processed asynchronously; that unknown fields are refused by name rather than dropped; that polling is free; that units are charged on submission and refunded on failure; and that webhook_url delivers a signed pointer, never the result. These are substantial behavioral traits beyond 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.

Conciseness5/5

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

The description is long, but every sentence conveys a distinct and necessary fact: purpose, parameter mapping, refusal behavior, ceilings, re-plan counting, response semantics, polling cost, billing, and webhook guidance. It is front-loaded with the core purpose and then structured to cover the tool's edge cases. Nothing is redundant or 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?

For a complex asynchronous submission tool with no annotations, the description is remarkably complete. It covers purpose, alternatives, parameter semantics, error behavior, quotas, billing, result retrieval via get_job, and optional webhook usage. The output schema may handle return value structure, but the description provides all contextual and operational knowledge an agent needs to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning. It explains the kind values map to specific synchronous input shapes, elaborates on the problem parameter with the exact-shape requirement and refusal behavior, and details webhook_url semantics including HTTPS-only, signed notifications, pointer-not-result, and the agent-should-poll caveat. This goes well beyond the schema descriptions.

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 first sentence states a specific verb and resource: 'Submit a problem too large to solve inside one request to the asynchronous lane, and get a job id back.' It clearly differentiates this tool from synchronous siblings like optimise_routes and replan_routes, and from get_job which polls the result. The purpose is unambiguous and distinct.

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?

The description explicitly states when to use the tool: for problems too large for a single synchronous request. It names the matching synchronous tools and says moving a working synchronous call changes nothing but the tool. It also gives a clear exclusion for webhook_url: 'An agent that can poll should not use it.' This is explicit when-to-use and when-not-to-use guidance.

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

All MapMap toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0
Disambiguation4/5

Most tools target a distinct action and resource pair, and descriptions are explicit about which tool fits which scenario. The closest overlaps—plan_ev_route vs cheapest_charging_along_route, and route vs plan_day vs order_stops vs optimise_routes—are mitigated by clear guidance, so an agent can usually pick correctly.

Naming Consistency4/5

Tool names overwhelmingly follow a verb_noun snake_case pattern (plan_ev_route, set_palette, list_style_layers) with a consistent geo_ prefix for geometry helpers. Minor deviations like elevation, route, and matrix are short and readable but break the strict verb_noun convention.

Tool Count2/5

At 39 tools, this surface is well past the 25+ threshold and feels heavy even for a broad mapping platform. The set spans routing, geocoding, places, styles, EV/fuel, telematics, usage, and feedback, which would be easier for an agent to navigate if split into smaller domain-focused servers.

Completeness4/5

For the stated breadth, coverage is strong: routing, multi-stop planning, VRP, EV/fuel detours, geocoding, places, geometry, style lifecycle, and telematics all have workable primary paths. Minor gaps like no style deletion, no route alternatives, and no batch geocoding are present but do not create dead ends for core workflows.

Resources