MapMap

plan_ev_route

Plan a whole electric-vehicle journey, charge stops included. Give origin and destination (plus optional waypoints) and a vehicle — a published profile ("small_hatch", "saloon", "suv", "van") and/or inline figures (battery_kwh, mass_kg, drag_area_m2, aux_kw, connectors) — with start_soc (default 0.9), min_arrival_soc (default 0.1), reserve_soc (default 0.1, the floor the charge must never drop below mid-route), optional connectors and min_kw filters and ambient_temperature_c. Energy comes from a published road-load physics model over the route's own legs; charge times are integrated over the vehicle's charging curve capped by the charge point, NOT energy divided by peak power, which is the single biggest error in naive EV planners. Returns the stops with arrive/depart state of charge, charge time and detour, a per-leg state-of-charge trace, and the journey's driving and charging time. IMPORTANT: when no plan exists — a charger desert, a connector mismatch, a gap wider than the car's range — the answer comes back with feasible: false, a reason and the furthest point on the route the car can actually reach. That is an ANSWER, not an error to retry: report the reason and never describe it as a plan. gradient_data says whether elevation was available: "absent" means consumption was modelled on the flat and under-reads a hilly route. There is no national charge-point registry, so ALWAYS show the returned coverage_note — an infeasible plan means "none from these operators", never "there are no chargers here" — and statuses are current only when availability_live is true. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset. Display the returned charging_attribution with the plan.

Input Schema

TableJSON Schema

Name	Required	Description
`min_kw`	No	Keep only charge points with a usable connector rated at least this many kW (e.g. 50 for rapid charging only).
`origin`	Yes	Where the journey starts.
`vehicle`	No	The vehicle. Omitted ⇒ the published "saloon" default, and the answer says which vehicle it used.
`start_soc`	No	State of charge at the start, 0–1 (default 0.9).
`waypoints`	No	Intermediate points the route must pass through, in order (at most 8). Charge stops are inserted around them.
`connectors`	No	Keep only charge points offering at least one of these connector standards: "type2", "type1", "ccs", "chademo", "tesla", "domestic", "other". This narrows the vehicle's own set, never widens it.
`destination`	Yes	Where it ends.
`reserve_soc`	No	The floor the state of charge must never fall below mid-route (default 0.1). Distinct from the arrival figure.
`min_arrival_soc`	No	Lowest acceptable state of charge on arrival (default 0.1).
`max_detour_minutes`	No	How far off the route a charge point may sit, as a detour in minutes (default 15, at most 120).
`ambient_temperature_c`	No	Ambient temperature in °C. Derates traction energy from a published study; cabin heating belongs in the vehicle's `aux_kw`.

Output Schema

TableJSON Schema

Name	Required	Description
`legs`	Yes	The driving legs, in order.
`stops`	Yes	The charge stops, in visit order. Always empty when `feasible` is false: a journey that cannot be completed has no stop list.
`reason`	No	The same cause in plain language, for the user.
`summary`	Yes	The plan at a glance.
`vehicle`	No	The vehicle the plan was computed for.
`feasible`	Yes	Whether the journey is possible at all. False means no plan exists — a charger desert, a connector mismatch, or a gap wider than the car's range. Report the `reason` and the furthest reachable point; never describe an infeasible answer as a plan.
`soc_trace`	Yes	State of charge at every point of the journey.
`reason_code`	No	Machine token for why no plan exists, when none does: "no_chargers_in_corridor", "connector_mismatch", "out_of_range", "dead_end", "below_min_kw", "chargers_unrated", "stop_limit", "dataset_empty", "no_charge_curve" or "unroutable".
`coverage_note`	Yes	Always present. What this deployment's charge-point dataset does and does not cover. An infeasible plan means "none from these operators", never "there are no chargers here". Show this alongside the answer.
`gradient_data`	Yes	"complete", "partial" or "absent". "absent" means the deployment had no elevation data and consumption was modelled on the flat, which under-reads a hilly route. Say so rather than presenting the figure as measured.
`profile_source`	No	"default" when a published profile supplied the figures, "inline" when the caller did.
`route_distance_m`	No	Distance of the planned route, metres.
`route_duration_s`	No	Driving time of the planned route, seconds.
`availability_live`	Yes	Whether charge-point statuses came from a live availability feed. A static planner is the default: without a feed, nothing in this answer is a claim about which bays are free right now.
`geometry_polyline6`	No	The planned journey's geometry as an encoded polyline6, through the charge stops.
`charging_attribution`	No	Attribution string for the charge-point operators actually used — display it with the plan (a licence obligation).
`furthest_reachable_lat`	No	Latitude of that furthest reachable point.
`furthest_reachable_lon`	No	Longitude of that furthest reachable point.
`furthest_reachable_position`	No	How far along the route the vehicle can get unaided, 0.0–1.0, when no plan exists.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedSep 23, 2026

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

AddedSep 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description fully carries the behavioral burden, and it does so exceptionally. It discloses the charging-curve integration model, the critical `feasible: false`/`reason` behavior as an answer rather than a retryable error, `gradient_data` caveats, the need to always display `coverage_note`, the `availability_live` freshness condition, the MapMap gateway dependency, and the display requirement for `charging_attribution`. This goes far beyond the schema and gives an agent actionable expectations.

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 every sentence carries important operational information: inputs, model assumptions, infeasible-result handling, data caveats, and display instructions. It is front-loaded with the purpose and then packs in critical warnings. It could be better structured with bullets for the caveats, but for a tool with this complexity, the length is justified and not padded.

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?

Given the tool's complexity, the high number of parameters, the existence of an output schema, and the absence of annotations, the description is remarkably complete. It covers inputs, vehicle semantics, failure modes, data quality caveats, live-status conditions, deployment prerequisites, and output display requirements. An agent has enough context to call the tool correctly and interpret results sensibly.

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 description coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining relationships and defaults: 'reserve_soc' as the mid-route floor, vehicle profiles versus inline overrides, connector/min_kw filtering, and the key modeling caveat that charge time is integrated over the charging curve rather than energy divided by peak power. This is more than the schema provides, though not every parameter is individually elaborated in prose.

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 opens with a specific verb and resource: 'Plan a whole electric-vehicle journey, charge stops included.' This clearly distinguishes it from generic routing tools like `route` or `optimise_routes` by emphasizing EV-specific charge-stop planning. It also covers the core inputs and output at a glance, so an agent can immediately identify what the tool does.

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?

The description gives clear context for when to use the tool: planning a full EV journey with charge stops, vehicle specification, and charging constraints. It does not explicitly name sibling alternatives or say 'use route instead when no charging is needed,' so it stops short of a 5. However, the context is specific enough that an agent would not confuse this with non-EV routing tools.

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

All MapMap tools Inspect

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

Need Help?