Skip to main content
Glama

matrix

Compute a travel time/distance matrix between origins (rows) and destinations (columns). Costing "auto", "truck" (with optional truck profile as in route), "bicycle", "pedestrian" or "motor_scooter". Returns durations_s[i][j] in seconds and distances_m[i][j] in metres; null cells are unreachable pairs. Up to 10,000 cells per call (origins × destinations). Optional exclude_polygons for before/after scenarios ("close this bridge and recompute the matrix"): an array of polygons, each an array of [lon, lat] pairs forming one ring (longitude FIRST) whose intersecting roads are excluded from every cell's path finding. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.

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": {
      "origins": "<origins>",
      "destinations": "<destinations>"
    },
    "name": "matrix"
  }
}

Input Schema

NameRequiredDescriptionDefault
truckNoTruck profile (dimensions + ADR declaration). Requires costing "truck".
costingNoCosting model: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter".auto
originsYesOrigin locations (matrix rows).
destinationsYesDestination locations (matrix columns).
exclude_polygonsNoAreas to avoid, scenario analysis ("close this bridge and recompute the matrix"): an array of polygons, each an array of `[lon, lat]` pairs forming one exterior ring (GeoJSON-style, longitude FIRST). Roads intersecting any ring are excluded from every cell's path finding; a pair no path joins without them stays null (the search is never widened round them). Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.

Output Schema

NameRequiredDescriptionDefault
distances_mYesTravel distances in metres, same shape as `durations_s`. Null cells are unreachable pairs.
durations_sYesTravel times in seconds; `durations_s[i][j]` is origin `i` → destination `j`. Null cells are unreachable pairs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / exclude_polygons / description
      Previous value: -"Areas to avoid, scenario analysis (\"close this bridge and\nrecompute the matrix\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nevery cell's path finding. Applies to the Valhalla engine;\nunsupported on the GraphHopper engine, where it is ignored."New value: +"Areas to avoid, scenario analysis (\"close this bridge and\nrecompute the matrix\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nevery cell's path finding; a pair no path joins without them stays\nnull (the search is never widened round them). Applies to the\nValhalla engine; unsupported on the GraphHopper engine, where it is\nignored."
  2. Changed2 schema fields changed
    • changedInput schema / $defs / TruckSpec / properties / tunnel_code / description
      Previous value: -"ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(—)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."New value: +"ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
    • changedInput schema / properties / exclude_polygons / description
      Previous value: -"Areas to avoid — scenario analysis (\"close this bridge and\nrecompute the matrix\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nevery cell's path finding. Applies to the Valhalla engine;\nunsupported on the GraphHopper engine, where it is ignored."New value: +"Areas to avoid, scenario analysis (\"close this bridge and\nrecompute the matrix\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nevery cell's path finding. Applies to the Valhalla engine;\nunsupported on the GraphHopper engine, where it is ignored."
  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. First observed

TDQS

A4.4/5.0
Behavior4/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 most of it: it discloses the return shape (`durations_s[i][j]`, `distances_m[i][j]`), that null cells mean unreachable, the 10,000-cell ceiling per call, and that excluded-area searches are never widened (a pair stays null). It also flags engine-dependent behavior — unsupported and silently ignored on GraphHopper — which is exactly the kind of caveat an agent cannot get elsewhere. It stops short of permission/rate-limit or error-mode detail.

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?

Purpose and matrix orientation are front-loaded, then costing, then return semantics, then the exclusion caveat — a sensible order. It is dense rather than padded, though the polygon-ring ordering rule ("longitude FIRST") and the Valhalla/GraphHopper caveat are each stated twice within the same passage.

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, yet the description still summarizes the return arrays and null semantics cheaply, and it covers the two things structured fields cannot: the per-call cell budget and engine-specific support for `exclude_polygons`. For a 5-parameter matrix tool, an agent has everything needed to call it correctly.

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 baseline is 3, but the description adds meaning beyond the schema: the 10,000-cell origins×destinations budget directly constrains how an agent should size those arrays, and the `truck` profile is cross-referenced to `route` for its shape. The `exclude_polygons` prose largely restates the schema field description, which caps this below 5.

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?

Opens with a specific verb and resource — 'Compute a travel time/distance matrix' — and immediately defines the shape: origins as rows, destinations as columns. That framing distinguishes it from single-pair siblings like `route` and from `optimise_routes`/`reachable_area` without needing to name them.

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?

Gives a concrete scenario for `exclude_polygons` ("close this bridge and recompute the matrix") and enumerates the costing choices with brief characterizations, which is real usage context. It never states the inverse — e.g. use `route` for a single origin/destination pair — so an agent must infer when this tool is preferable to its siblings.

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