Skip to main content
Glama

match_trace

Snap a recorded GPS trace to the road network and say what it actually travelled over. Provide shape (2 to 2000 recorded points, oldest first) or encoded_polyline (the same trace as a polyline6 string) (not both) plus the costing it was travelled under: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". Costing decides which roads the trace may match onto, so a walk matched as "auto" snaps to the carriageway rather than the footpath. Returns the matched path as geometry_polyline6 (the snapped roads, not your raw points) with its distance_m and duration_s, then the roll-ups: by_road_class and by_admin (distance and time, longest first), by_surface (distance), and toll, bridge and tunnel totals. This is how you turn a dashcam or telematics log into a report, which country and region the driving happened in, how much of it was motorway, how much was tolled, how much was unpaved. Honesty: the roll-ups are summed per matched road segment, so they need not add up to distance_m exactly, and segments the map records no surface or admin area for are left out of that breakdown rather than filed under a guess, an entry in by_admin with null codes is exactly that, counted and not attributed. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY); there is no direct-backend fallback.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "match_trace"
  }
}

Input Schema

NameRequiredDescriptionDefault
shapeNoThe trace as an ordered list of recorded points, oldest first. Between 2 and 2000 points. Provide this or `encoded_polyline`.
costingNoCosting model the trace was travelled under: `auto` (default), `truck`, `bicycle`, `pedestrian` or `motor_scooter`. It decides which roads the trace may be matched onto, so a walked trace matched as `auto` snaps to the carriageway rather than the path.
encoded_polylineNoThe trace as a Google encoded polyline with six digits of decimal precision (polyline6), the geometry `route` and `match_trace` themselves return. Provide this or `shape`.

Output Schema

NameRequiredDescriptionDefault
tollYesTolled portion of the matched path.
bridgeYesBridge portion of the matched path.
tunnelYesTunnel portion of the matched path.
costingYesCosting the trace was matched under.
summaryYesOne-line human summary of the match, for reading aloud.
by_adminYesDistance and time by administrative area, longest first. An entry whose codes are all null covers segments the graph could not place in any admin area, counted honestly rather than guessed at.
by_surfaceYesDistance by road surface (`paved`, `paved_smooth`, `gravel`, …), longest first. Empty when the graph records no surface for any matched segment.
distance_mYesLength of the matched path in metres.
duration_sYesTravel time along the matched path in seconds, from the engine's own time model.
edge_countYesHow many road segments the trace matched onto.
by_road_classYesDistance and time by road class (`motorway`, `primary`, `residential`, …), longest first.
geometry_polyline6YesThe matched path as a Google encoded polyline with six digits of decimal precision (polyline6). This is the trace snapped to real roads, not the raw input.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / $defs / AdminAreaSummary / required
      Previous value: -[
      -  "distance_m",
      -  "duration_s",
      -  "edge_count"
      -]New value: +[
      +  "country_code",
      +  "country",
      +  "state_code",
      +  "state",
      +  "distance_m",
      +  "duration_s",
      +  "edge_count"
      +]
  2. Changed2 schema fields changed
    • changedInput schema / properties / encoded_polyline / description
      Previous value: -"The trace as a Google encoded polyline with six digits of decimal\nprecision (polyline6) — the geometry `route` and `match_trace`\nthemselves return. Provide this or `shape`."New value: +"The trace as a Google encoded polyline with six digits of decimal\nprecision (polyline6), the geometry `route` and `match_trace`\nthemselves return. Provide this or `shape`."
    • changedOutput schema / properties / by_admin / description
      Previous value: -"Distance and time by administrative area, longest first. An entry\nwhose codes are all null covers segments the graph could not place\nin any admin area — counted honestly rather than guessed at."New value: +"Distance and time by administrative area, longest first. An entry\nwhose codes are all null covers segments the graph could not place\nin any admin area, counted honestly rather than guessed at."
  3. Changed5 schema fields changed
    • addedInput schema / $defs / LatLon / anyOf
      Added value: +[
      +  {
      +    "properties": {
      +      "lat": {
      +        "description": "Latitude in decimal degrees (−90 to 90).",
      +        "format": "double",
      +        "type": "number"
      +      },
      +      "lon": {
      +        "description": "Longitude in decimal degrees (−180 to 180).",
      +        "format": "double",
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "lat",
      +      "lon"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "description": "GeoJSON position [lon, lat]: longitude FIRST.",
      +    "items": {
      +      "format": "double",
      +      "type": "number"
      +    },
      +    "maxItems": 2,
      +    "minItems": 2,
      +    "type": "array"
      +  }
      +]
    • changedInput schema / $defs / LatLon / description
      Previous value: -"A WGS84 coordinate pair in decimal degrees."New value: +"A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
    • removedInput schema / $defs / LatLon / properties
      Removed value: -{
      -  "lat": {
      -    "description": "Latitude in decimal degrees (−90 to 90).",
      -    "format": "double",
      -    "type": "number"
      -  },
      -  "lon": {
      -    "description": "Longitude in decimal degrees (−180 to 180).",
      -    "format": "double",
      -    "type": "number"
      -  }
      -}
    • removedInput schema / $defs / LatLon / required
      Removed value: -[
      -  "lat",
      -  "lon"
      -]
    • removedInput schema / $defs / LatLon / type
      Removed value: -"object"
  4. Added

TDQS

A4.4/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 that roll-ups are summed per matched segment and "need not add up to `distance_m` exactly", that unrecorded surface/admin segments are omitted rather than guessed, that null admin codes mean counted-but-unattributed, and that a MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY) is required with no direct-backend fallback. That is exactly the kind of constraint an agent cannot infer from schema or annotations.

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 opening sentence is front-loaded and decisive, and the input constraints come before the return-field enumeration. It is dense but not padded; the only slack is the long roll-up inventory (`by_road_class`, `by_admin`, `by_surface`, toll/bridge/tunnel) which the output schema already enumerates.

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 3-parameter analysis tool with an output schema, the description covers inputs, the costing hazard, the returned roll-ups' caveats, and the gateway prerequisite. Nothing material an agent needs to invoke 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 ordering ("oldest first"), the 2–2000 point bound, the shape-vs-polyline exclusivity, and the costing list are already fully documented in the schema, and the description largely restates them. The one genuine addition is the worked example of costing's effect ("a walk matched as `auto` snaps to the carriageway rather than the footpath"), which is also present in the schema's `costing` description. Baseline 3 fits.

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?

"Snap a recorded GPS trace to the road network and say what it actually travelled over" gives a specific verb (snap/match) and resource (GPS trace on road network), plus the downstream purpose (attribute what was travelled). It is clearly distinguishable from routing/matrix siblings, which compute paths rather than reconcile observed tracks.

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 states input paths explicitly ("Provide `shape` ... or `encoded_polyline` ... (not both)") and gives a concrete usage context: "This is how you turn a dashcam or telematics log into a report." It warns that the wrong `costing` yields wrong matching results. What's absent is an explicit when-not-to-use or a named alternative for plain point-to-point routing.

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