Skip to main content
Glama

MapMap

by ai.mapmap
OverviewDiscussionsAdmin

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

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

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.

  1. 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."
  2. 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 202-and-job-id return semantics (not a plan), the polling loop via get_job until terminal status, that polling is free while submission is metered, that units are refunded in full on failure, that unknown fields are refused by name, the exact ceilings (2,000 locations / 40,000 matrix elements) versus synchronous caps, and that webhook delivery requires a signing secret. This is unusually complete behavioral context for a mutation/queueing tool.

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?

The description is long but front-loaded with purpose and return semantics, and most sentences carry distinct information (ceilings, refunds, refusal-by-name, webhook guidance). There is minor redundancy, e.g. the 'moving a synchronous call changes nothing' point appears both in the description and again in the problem schema field.

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 not be explained, yet the description still clarifies that the immediate answer is a job id rather than a plan and describes the polling path to the result. For a 3-parameter async submission tool with real consequences (metering, refunds, queuing), nothing an agent needs 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 description coverage is 100%, so kind, problem, and webhook_url are already fully documented in the schema, and the description largely restates that content (kind selects body shape, problem mirrors the synchronous input, webhook is https-only and signed). It adds little parameter detail the schema does not already carry, so the 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?

The description 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') and explicitly contrasts itself with the synchronous siblings optimise_routes, replan_routes, and matrix. An agent can distinguish this tool from those without opening any 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 gives explicit when-to-use criteria (problem too large for a single request), names the three synchronous alternatives and the exact shape each maps to, and states the migration rule ('changes nothing but which tool you call it with'). It also gives a when-not-to-use for webhook_url ('An agent that can poll should not use it').

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