MapMap

cheapest_fuel_along_route

Find the cheapest fuel along a route, with the REAL extra travel time of stopping at each station — never a straight-line guess. Provide origin + destination (a route is computed) or an existing route's geometry_polyline6, plus a fuel code ("diesel" default, "petrol_95", "petrol_98", "premium_diesel", "e85", "lpg") and max_detour_minutes (default 10). Stations come from the live open-data price feeds (UK CMA retailer scheme and/or the statutory Fuel Finder, FR prix-carburants, DE Tankerkoenig; the response's fuel_attribution names the ones actually matched), are priced through the routing engine with your costing (a truck profile makes detours respect dimensional/ADR restrictions) and ranked freshest-priced first and cheapest within that. Each result carries price {value, currency, updated_at, stale}, detour_minutes/detour_km, and saving_per_litre vs the cheapest on-route baseline (pass fill_litres to also get saving_total). stale = not verifiably fresher than 24 h: true unless BOTH the price's own updated_at and the snapshot's fetch time are inside that window, and true whenever either is missing. A stale price is ranked below every fresh one, is never the baseline, and carries NO saving_per_litre — quote it as "last seen at X on ", never as a saving. say is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the number, the detour and the honest qualifier already in it. Prefer reading it verbatim to writing your own summary: a stale price's line states the figure and the day it was last seen and claims no saving, and an empty result's line names the cause rather than implying there is no fuel on that road. Requires the MapMap gateway; answers a clear error when the deployment has no fuel-price dataset. Display the returned fuel_attribution with the prices.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fuel`	No	Which fuel to price: "diesel" (default), "petrol_95", "petrol_98", "premium_diesel", "e85" or "lpg" (aliases "petrol", "unleaded", "e10", "super_unleaded", "e5", "b7" and "sdv" are accepted).
`truck`	No	Truck profile (dimensions + ADR declaration). Requires costing "truck"; the detours then respect dimensional/ADR restrictions.
`origin`	No	Route origin (with `destination`, when no geometry is given).
`costing`	No	Costing model for the route and detour matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter".	auto
`destination`	No	Route destination.
`fill_litres`	No	Optional fill size in litres; each result then also carries `saving_total` = `saving_per_litre` × `fill_litres`.
`max_results`	No	Maximum results (default 5, at most 25).
`geometry_polyline6`	No	An existing route geometry as an encoded polyline6 (the `route` tool's `geometry_polyline6`). Provide either this or `origin` + `destination`, not both.
`max_detour_minutes`	No	Largest acceptable detour in minutes (default 10, at most 120).

Output Schema

TableJSON Schema

Name	Required	Description
`say`	Yes	Always present. The whole answer as one short spoken line, composed by the gateway: the number, the detour, and the honest qualifier where one applies. Safe to read to a driver verbatim, and safe on an empty result, where it names the cause rather than implying there is no fuel on the road. A stale price's line states the figure and the day it was last seen and claims no saving.
`fuel`	Yes	The normalised fuel code that was priced (e.g. "diesel").
`costing`	Yes	The costing the detours were priced with.
`results`	Yes	Stations within the detour budget, cheapest first (price, then detour).
`baseline`	Yes	The cheapest effectively-on-route option per currency (empty when no station sits on the route itself).
`candidate_cap`	Yes	The matrix fan-out cap in force.
`route_length_m`	Yes	Length of the route geometry in metres.
`fuel_attribution`	No	Attribution string for the fuel-price data sources actually returned — display it with the prices (a licence obligation).
`route_distance_m`	No	Direct origin→destination distance in metres.
`route_duration_s`	No	Direct origin→destination travel time in seconds (same estimator as the detour legs), when routable.
`candidates_costed`	Yes	Candidates actually priced through the engine (fan-out capped at `candidate_cap`, cheapest kept).
`max_detour_minutes`	Yes	The detour budget applied, minutes.
`candidates_considered`	Yes	Stations selling the fuel that passed the corridor pre-filter.

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

Changed2 schema fields changedSep 21, 2026

addedOutput schema / properties / say

Added value: +{
+  "description": "**Always present.** The whole answer as one short spoken line,\ncomposed by the gateway: the number, the detour, and the honest\nqualifier where one applies. Safe to read to a driver verbatim,\nand safe on an empty result, where it names the cause rather than\nimplying there is no fuel on the road. A stale price's line states\nthe figure and the day it was last seen and claims no saving.",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "fuel",
-  "costing",
-  "route_length_m",
-  "candidates_considered",
-  "candidates_costed",
-  "candidate_cap",
-  "max_detour_minutes",
-  "baseline",
-  "results"
-]New value: +[
+  "fuel",
+  "costing",
+  "route_length_m",
+  "candidates_considered",
+  "candidates_costed",
+  "candidate_cap",
+  "max_detour_minutes",
+  "baseline",
+  "results",
+  "say"
+]

Changed3 schema fields changedSep 17, 2026

changedOutput schema / $defs / FuelBaseline / description

Previous value: -"The cheapest effectively-on-route option in one currency — what the\ndriver pays by just pulling in without a detour; the reference the\nper-result savings are computed against."New value: +"The cheapest effectively-on-route option in one currency — what the\ndriver pays by just pulling in without a detour; the reference the\nper-result savings are computed against. Only a fresh price is\neligible, so this is `stale: false` by construction."

changedOutput schema / $defs / FuelPriceQuote / properties / stale / description

Previous value: -"True when the price could not be verified fresher than 24 hours —\ntreat it as indicative, not bindable."New value: +"True when the price could not be verified fresher than 24 hours:\nunless BOTH the source's own `updated_at` and the snapshot's fetch\ntime fall inside that window, and always when either is missing.\nTreat it as indicative, not bindable — say \"last seen at X on\n<date>\", never quote it as today's price or as a saving."

changedOutput schema / $defs / FuelStationHit / properties / saving_per_litre / description

Previous value: -"Per-litre saving against the cheapest effectively-on-route station\nin the same currency (negative = dearer than staying on route).\nAbsent when no station sits on the route itself in this currency."New value: +"Per-litre saving against the cheapest effectively-on-route station\nin the same currency (negative = dearer than staying on route).\nAbsent when no FRESH station sits on the route itself in this\ncurrency, and always absent on a stale result: an unverifiable\nprice may state a number but never claim a saving."

First observedSep 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 carries the full burden and does an excellent job. It discloses live data sources, the definition of 'stale' with exact conditions, ranking rules, the behavior of stale prices (never baseline, no saving), and the instruction to quote them honestly. It also explains the 'say' field's composition and the error case for missing datasets. This is exceptional transparency.

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 contributes. It is well-structured with the purpose first, then input modes, data sources, output details, stale-price handling, and the 'say' field guidance. It is not overly verbose given the complexity, though it could be tightened slightly without losing essential information.

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 9 parameters, 100% schema coverage, and presence of an output schema, the description is remarkably complete. It covers all input modes, fuel types, costing models, the stale-price logic, the 'say' field composition, attribution display, and error conditions. Nothing essential for correct invocation 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?

The schema already describes all parameters (100% coverage), so baseline is 3. The description adds meaning beyond that: it explains the mutual exclusivity of origin/destination vs geometry_polyline6, the effect of fill_litres on saving_total, the truck profile's impact on detour restrictions, and the aliases for fuel codes. This is valuable added context.

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 states a specific verb ('Find the cheapest fuel'), a clear resource (fuel along a route), and distinguishes itself from the sibling 'cheapest_charging_along_route' by focusing on fuel types. It also contrasts with generic search tools by emphasizing real detour times and price freshness. The scope is unambiguous.

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 explicit input modes (origin/destination or geometry_polyline6), defaults for fuel and max_detour_minutes, and explains the 'say' field should be read verbatim. It does not explicitly name alternative tools, but the usage context is clear. It also mentions the MapMap gateway requirement and error behavior, which helps the agent decide when to use it.

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?