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.

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 carries the full burden and does so impressively. It explains the physics-based energy model, warns that charge time is not energy divided by peak power, and details infeasible-answer semantics ('feasible: false' is an answer, not an error). It also covers gradient-data caveats, coverage_note display requirements, availability_live status, and the MapMap gateway dependency.

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 front-loaded with the core purpose and has no filler; each sentence adds a meaningful caveat or behavioral clarification. It uses an 'IMPORTANT' marker and 'ALWAYS' to emphasize critical operational guidance. It could be tightened into shorter paragraphs or bullets for easier scanning, but it earns its length given the complexity.

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 an 11-parameter tool with an output schema, the description covers everything an agent needs: input composition, defaults, infeasible-result handling, data caveats, coverage note requirements, and even display instructions for charging_attribution. It also warns about deployment environments without a charge-point dataset. Nothing critical 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; the description adds meaning beyond the schema by explaining reserve_soc as the mid-route floor, clarifying connectors/min_kw as filters, and describing how vehicle profiles and inline figures interact. It also clarifies defaults for start_soc, min_arrival_soc, and reserve_soc in the flow of the description. The rich schema still does most of the parameter documentation work, but the description genuinely supplements it.

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 general routing siblings like route or optimize_routes by emphasizing the EV-specific charge-stop planning scope. It also states exactly what it returns: stops, state-of-charge traces, and driving/charging times.

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 usage context is clear: this tool is for planning a full EV journey with charge stops, including vehicle specification, SOC thresholds, and connector filters. The description implies it is the right choice when charge stops, charging curves, and EV-specific feasibility matter, while siblings like route or reachable_area serve other purposes. It does not explicitly name alternatives or state when not to use it, 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 tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0

Disambiguation4/5

Most tools target a distinct action and resource pair, and descriptions are explicit about which tool fits which scenario. The closest overlaps—plan_ev_route vs cheapest_charging_along_route, and route vs plan_day vs order_stops vs optimise_routes—are mitigated by clear guidance, so an agent can usually pick correctly.

Naming Consistency4/5

Tool names overwhelmingly follow a verb_noun snake_case pattern (plan_ev_route, set_palette, list_style_layers) with a consistent geo_ prefix for geometry helpers. Minor deviations like elevation, route, and matrix are short and readable but break the strict verb_noun convention.

Tool Count2/5

At 39 tools, this surface is well past the 25+ threshold and feels heavy even for a broad mapping platform. The set spans routing, geocoding, places, styles, EV/fuel, telematics, usage, and feedback, which would be easier for an agent to navigate if split into smaller domain-focused servers.

Completeness4/5

For the stated breadth, coverage is strong: routing, multi-stop planning, VRP, EV/fuel detours, geocoding, places, geometry, style lifecycle, and telematics all have workable primary paths. Minor gaps like no style deletion, no route alternatives, and no batch geocoding are present but do not create dead ends for core workflows.

Resources

Need Help?