Skip to main content
Glama

Calculate a driving route

calculate_route
Read-onlyIdempotent

Calculates a driving route's distance, time, and bounding box, with up to two alternatives when no waypoints are set; optionally returns route geometry.

Instructions

Calculate a driving route and return its distance (km), driving time (minutes) and bounding box, with up to 2 alternatives when there are no waypoints. Ends can be place names, "lat,lon" text or coordinates. To find fuel along the way, call cheapest_fuel_on_route instead: it routes and searches in one call. Set include_geometry only to pass the line to find_route_stations; it can be up to 2000 points.

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": "calculate_route"
  }
}

Input Schema

NameRequiredDescriptionDefault
originNoStart as a place name ("Madrid") or "lat,lon" text ("40.4168,-3.7038"). Or give origin_lat and origin_lon.
dest_latNoEnd latitude, decimal degrees.
dest_lonNoEnd longitude, decimal degrees.
waypointsNoOptional stops in order, as [lon, lat] pairs (longitude first), at most 5. Example: [[-1.13, 40.34]].
origin_latNoStart latitude, decimal degrees.
origin_lonNoStart longitude, decimal degrees.
destinationNoEnd as a place name ("Valencia") or "lat,lon" text. Or give dest_lat and dest_lon.
include_geometryNoInclude each route's GeoJSON LineString ([lon, lat] points). Default false.

Output Schema

NameRequiredDescriptionDefault
originYes
routesYes
destinationYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changedv0.2.1
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / dest_lat / description
      Previous value: -"Destination latitude"New value: +"End latitude, decimal degrees."
    • addedInput schema / properties / dest_lat / maximum
      Added value: +90
    • addedInput schema / properties / dest_lat / minimum
      Added value: +-90
    • changedInput schema / properties / dest_lon / description
      Previous value: -"Destination longitude"New value: +"End longitude, decimal degrees."
    • addedInput schema / properties / dest_lon / maximum
      Added value: +180
    • addedInput schema / properties / dest_lon / minimum
      Added value: +-180
    • addedInput schema / properties / destination
      Added value: +{
      +  "description": "End as a place name (\"Valencia\") or \"lat,lon\" text. Or give dest_lat and dest_lon.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / include_geometry
      Added value: +{
      +  "default": false,
      +  "description": "Include each route's GeoJSON LineString ([lon, lat] points). Default false.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / origin
      Added value: +{
      +  "description": "Start as a place name (\"Madrid\") or \"lat,lon\" text (\"40.4168,-3.7038\"). Or give origin_lat and origin_lon.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / origin_lat / description
      Previous value: -"Origin latitude"New value: +"Start latitude, decimal degrees."
    • addedInput schema / properties / origin_lat / maximum
      Added value: +90
    • addedInput schema / properties / origin_lat / minimum
      Added value: +-90
    • changedInput schema / properties / origin_lon / description
      Previous value: -"Origin longitude"New value: +"Start longitude, decimal degrees."
    • addedInput schema / properties / origin_lon / maximum
      Added value: +180
    • addedInput schema / properties / origin_lon / minimum
      Added value: +-180
    • changedInput schema / properties / waypoints / description
      Previous value: -"Optional JSON array of waypoints as [[lon,lat],...]"New value: +"Optional stops in order, as [lon, lat] pairs (longitude first), at most 5. Example: [[-1.13, 40.34]]."
    • addedInput schema / properties / waypoints / items
      Added value: +{
      +  "items": {
      +    "type": "number"
      +  },
      +  "maxItems": 2,
      +  "minItems": 2,
      +  "type": "array"
      +}
    • addedInput schema / properties / waypoints / maxItems
      Added value: +5
    • changedInput schema / properties / waypoints / type
      Previous value: -"string"New value: +"array"
    • changedInput schema / required
      Previous value: -[
      -  "origin_lon",
      -  "origin_lat",
      -  "dest_lon",
      -  "dest_lat"
      -]New value: +[]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "destination": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "city": {
      +          "type": "string"
      +        },
      +        "country": {
      +          "type": "string"
      +        },
      +        "lat": {
      +          "type": "number"
      +        },
      +        "lon": {
      +          "type": "number"
      +        },
      +        "name": {
      +          "type": "string"
      +        },
      +        "state": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "name",
      +        "lat",
      +        "lon"
      +      ],
      +      "type": "object"
      +    },
      +    "origin": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "city": {
      +          "type": "string"
      +        },
      +        "country": {
      +          "type": "string"
      +        },
      +        "lat": {
      +          "type": "number"
      +        },
      +        "lon": {
      +          "type": "number"
      +        },
      +        "name": {
      +          "type": "string"
      +        },
      +        "state": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "name",
      +        "lat",
      +        "lon"
      +      ],
      +      "type": "object"
      +    },
      +    "routes": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "bbox": {
      +            "items": {
      +              "type": "number"
      +            },
      +            "type": [
      +              "null",
      +              "array"
      +            ]
      +          },
      +          "distance_km": {
      +            "type": "number"
      +          },
      +          "duration_min": {
      +            "type": "number"
      +          },
      +          "geometry": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "coordinates": {
      +                "items": {
      +                  "items": {
      +                    "type": "number"
      +                  },
      +                  "type": [
      +                    "null",
      +                    "array"
      +                  ]
      +                },
      +                "type": [
      +                  "null",
      +                  "array"
      +                ]
      +              },
      +              "type": {
      +                "enum": [
      +                  "LineString"
      +                ],
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "type",
      +              "coordinates"
      +            ],
      +            "type": "object"
      +          },
      +          "points": {
      +            "description": "Number of points in the route line",
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "distance_km",
      +          "duration_min",
      +          "points"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "origin",
      +    "destination",
      +    "routes"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real behavioral detail beyond them: alternatives are capped at 2 and only appear when there are no waypoints, and the geometry payload can reach 2000 points. It stops short of stating any rate or size limits on the route call itself.

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?

Three tight sentences, front-loaded with what the tool returns, then the alternative, then the parameter caveat. No filler, and each clause carries a decision-relevant fact.

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?

Eight optional parameters and an output schema mean the schema and output do most of the structural work; the description covers the non-obvious behavioral facts (alternatives rule, geometry cost, sibling routing) that the structured data cannot express. Nothing an agent needs before calling it is missing.

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 genuine interpretation: the interaction between waypoints and the availability of alternatives, and the fact that include_geometry exists solely to feed find_route_stations. The place-name vs. 'lat,lon' vs. coordinate-pair input forms are already in the schema and are only lightly echoed.

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?

States a specific verb and resource (calculate a driving route) plus exactly what comes back: distance in km, driving time in minutes, and a bounding box. It also distinguishes itself from cheapest_fuel_on_route and find_route_stations, so an agent can select it without opening sibling schemas.

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?

Gives an explicit alternative with its trigger condition: 'To find fuel along the way, call cheapest_fuel_on_route instead: it routes and searches in one call.' It also constrains include_geometry to the single case where the line is fed to find_route_stations, which prevents a costly misuse.

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