Skip to main content
Glama
Sign In

MapMap

by ai.mapmap
OverviewDiscussionsAdmin

coverage_guidance

Turn-by-turn guidance for one drive of a finished coverage plan (submit_optimise_job with kind: "coverage", read with get_job), in one call. Give job_id (the coverage job, the caller's own and succeeded), chunk_id (the outing's id in result.chunks, from 1) and drive: "outing" (default, the outing itself), "transfer" (the drive into that outing from the previous one's end, or from where the car is; chunk_loops plans) or "transfer_to_start" (the plan's drive back to its start; no chunk_id). The gateway walks every piece of that drive's trace_route_parts on the engine's exact edge walk and answers one trip: legs has one entry per piece in driving order, each with its maneuvers, plus the whole drive's distance_m, duration_s and geometry_polyline6. Pieces join mid-street wherever the plan allowed: a leg's closing arrival and the next leg's opening departure at the same point mean carry straight on, not stop. Exact or nothing: it never falls back to map matching (which drops streets driven in and straight back out), so a piece the engine refuses is an error naming that piece and the engine's own words. Metered by the gateway as one call at the size of a /trace_route of the drive (one call per started block of shape points, never fewer than the pieces). A refused piece keeps those quota units (the engine did the work) but takes no prepaid credit or x402 payment; a request refused before walking (unknown or unfinished job, no such outing) is not billed. Premium for a truck plan. 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": {
      "job_id": "<job_id>"
    },
    "name": "coverage_guidance"
  }
}

Input Schema

NameRequiredDescriptionDefault
driveNo`outing` (the default), `transfer` (the drive into that outing) or `transfer_to_start` (the plan's drive back to its start).outing
job_idYesThe coverage job's id, as `submit_optimise_job` (`kind: "coverage"`) returned it. The job must be this key's own (or another key of the same account) and `succeeded`.
chunk_idNoThe outing's `id` in the job's `result.chunks` (from 1). Required unless `drive` is `transfer_to_start`.

Output Schema

NameRequiredDescriptionDefault
legsYesOne leg per piece, in driving order, each with its maneuvers.
driveYesThe drive guided: `outing`, `transfer` or `transfer_to_start`.
job_idYesThe job it came from.
piecesYesPieces walked, one leg each.
summaryYesOne-line summary of the drive.
chunk_idNoThe outing's `id`, when one was named.
distance_mYesThe whole drive's length, metres.
duration_sYesThe whole drive's estimated driving time, seconds.
geometry_polyline6YesThe whole drive's geometry as the engine walked it, polyline6, legs joined at their shared points.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/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 unusually well: it discloses the exact-or-nothing behavior and refusal to map-match, names the failure mode (error naming the refused piece in the engine's words), and explains billing in detail (quota units kept on a refused walk, no prepaid credit or x402 charge, requests refused before walking are free), plus a truck premium and a gateway prerequisite.

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 purpose and the three drive values are front-loaded, and most sentences carry distinct information (legs layout, mid-street joins, billing). It is still a single dense paragraph where billing and error rules are interleaved with return-shape detail, so a little restructuring would make it faster to scan.

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?

Despite high complexity — three drive modes, a chunk reference, billing, and refusal semantics — the description covers prerequisites, error behavior, cost model, and how legs join mid-street. An output schema exists, yet the description's brief note on `legs`, `distance_m`, `duration_s` and `geometry_polyline6` is proportionate rather than redundant, leaving no material gap for correct invocation.

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 the baseline is 3, but the description adds real meaning beyond the schema: it clarifies chunk_id is 1-based and sourced from `result.chunks`, and explains 'transfer' in terms of the previous outing's end or the car's current position and chunk_loops plans. It also clarifies the interaction where transfer_to_start ignores chunk_id, which the schema only implies.

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 states a specific verb and resource — 'turn-by-turn guidance for one drive of a finished coverage plan' — and anchors it to concrete siblings ('submit_optimise_job' with kind: "coverage", read with 'get_job'). It is clearly distinct from generic routing siblings like 'route' or 'trace_route' because it is scoped to a finished plan's stored pieces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the operating conditions precisely: the job must be the caller's own and 'succeeded', chunk_id comes from `result.chunks` from 1, and it spells out which of the three drives to pick and that transfer_to_start takes no chunk_id. What it lacks is an explicit when-not/alternative pointer, e.g. when to prefer 'trace_route' or 'match_trace' instead, so it stops short of a 5.

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