Skip to main content
Glama

Find nearest fuel or EV stations

find_nearest_stations
Read-onlyIdempotent

Find fuel stations or EV chargers nearest a latitude/longitude or place name, with current prices; sort by distance or price.

Instructions

Find the fuel stations or EV chargers closest to a point, with current prices. Give the point as lat and lon, or as a place name in near (geocoded for you). sort_by=distance (default) returns the nearest; sort_by=price returns the cheapest among the 50 nearest within the radius. Prices are per litre (per kg for CNG, LNG and H2, per kWh for EV) in the station's local currency. Covers about 40 countries, mostly in Europe; pumperly://stats lists them.

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": {
      "fuel": "<fuel>"
    },
    "name": "find_nearest_stations"
  }
}

Input Schema

NameRequiredDescriptionDefault
latNoLatitude of the search point in decimal degrees, e.g. 40.4168. Give with lon, or use near instead.
lonNoLongitude of the search point in decimal degrees, e.g. -3.7038. Give with lat, or use near instead.
fuelYesFuel code. Common ones: B7 = diesel, E5 = petrol 95, E10 = petrol 95 E10, E5_98 = petrol 98, LPG = autogas, EV = charging. The pumperly://fuel-types resource lists all 16 with labels and price units.
nearNoPlace name or address to search around, e.g. "Atocha, Madrid". Used when lat and lon are not given.
limitNoHow many stations to return, 1 to 50. Default 5.
sort_byNodistance (nearest first, default) or price (cheapest first).distance
radius_kmNoSearch radius in km, 0.5 to 100. Default 10.

Output Schema

NameRequiredDescriptionDefault
fuelYes
unitYesWhat prices are per: L, kg or kWh
foundYes
centerNo
pricesYes
sort_byYes
returnedYes
stationsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changedv0.2.1
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / fuel / description
      Previous value: -"Fuel type code (e.g. B7, E5, E10, E85, LPG, CNG, LNG, EV)"New value: +"Fuel code. Common ones: B7 = diesel, E5 = petrol 95, E10 = petrol 95 E10, E5_98 = petrol 98, LPG = autogas, EV = charging. The pumperly://fuel-types resource lists all 16 with labels and price units."
    • addedInput schema / properties / fuel / enum
      Added value: +[
      +  "B7",
      +  "B7_PREMIUM",
      +  "B10",
      +  "B_AGRICULTURAL",
      +  "HVO",
      +  "E5",
      +  "E5_PREMIUM",
      +  "E10",
      +  "E5_98",
      +  "E98_E10",
      +  "LPG",
      +  "CNG",
      +  "LNG",
      +  "H2",
      +  "EV",
      +  "ADBLUE"
      +]
    • changedInput schema / properties / lat / description
      Previous value: -"Latitude of the search centre"New value: +"Latitude of the search point in decimal degrees, e.g. 40.4168. Give with lon, or use near instead."
    • addedInput schema / properties / lat / maximum
      Added value: +90
    • addedInput schema / properties / lat / minimum
      Added value: +-90
    • addedInput schema / properties / limit / default
      Added value: +5
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of results (default 5)"New value: +"How many stations to return, 1 to 50. Default 5."
    • addedInput schema / properties / limit / maximum
      Added value: +50
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / lon / description
      Previous value: -"Longitude of the search centre"New value: +"Longitude of the search point in decimal degrees, e.g. -3.7038. Give with lat, or use near instead."
    • addedInput schema / properties / lon / maximum
      Added value: +180
    • addedInput schema / properties / lon / minimum
      Added value: +-180
    • addedInput schema / properties / near
      Added value: +{
      +  "description": "Place name or address to search around, e.g. \"Atocha, Madrid\". Used when lat and lon are not given.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / radius_km / default
      Added value: +10
    • changedInput schema / properties / radius_km / description
      Previous value: -"Search radius in kilometres (default 10)"New value: +"Search radius in km, 0.5 to 100. Default 10."
    • addedInput schema / properties / radius_km / maximum
      Added value: +100
    • addedInput schema / properties / radius_km / minimum
      Added value: +0.5
    • addedInput schema / properties / sort_by
      Added value: +{
      +  "default": "distance",
      +  "description": "distance (nearest first, default) or price (cheapest first).",
      +  "enum": [
      +    "distance",
      +    "price"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "lat",
      -  "lon",
      -  "fuel"
      -]New value: +[
      +  "fuel"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "center": {
      +      "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": [
      +        "null",
      +        "object"
      +      ]
      +    },
      +    "found": {
      +      "type": "integer"
      +    },
      +    "fuel": {
      +      "type": "string"
      +    },
      +    "prices": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "count": {
      +            "type": "integer"
      +          },
      +          "currency": {
      +            "type": "string"
      +          },
      +          "max": {
      +            "type": "number"
      +          },
      +          "median": {
      +            "type": "number"
      +          },
      +          "min": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "currency",
      +          "count",
      +          "min",
      +          "median",
      +          "max"
      +        ],
      +        "type": "object"
      +      },
      +      "type": [
      +        "null",
      +        "array"
      +      ]
      +    },
      +    "returned": {
      +      "type": "integer"
      +    },
      +    "sort_by": {
      +      "enum": [
      +        "price",
      +        "distance",
      +        "route"
      +      ],
      +      "type": "string"
      +    },
      +    "stations": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "address": {
      +            "type": "string"
      +          },
      +          "brand": {
      +            "type": "string"
      +          },
      +          "city": {
      +            "type": "string"
      +          },
      +          "country": {
      +            "description": "ISO 3166-1 alpha-2 country code",
      +            "type": "string"
      +          },
      +          "currency": {
      +            "description": "ISO 4217 currency of price",
      +            "type": "string"
      +          },
      +          "distance_km": {
      +            "description": "Straight-line distance from the search point, km",
      +            "type": [
      +              "null",
      +              "number"
      +            ]
      +          },
      +          "ev_fees": {
      +            "additionalProperties": true,
      +            "type": "object"
      +          },
      +          "lat": {
      +            "type": "number"
      +          },
      +          "lon": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "power_kw": {
      +            "description": "EV only: maximum charging power, kW",
      +            "type": [
      +              "null",
      +              "number"
      +            ]
      +          },
      +          "price": {
      +            "description": "Price per unit in currency",
      +            "type": [
      +              "null",
      +              "number"
      +            ]
      +          },
      +          "reported_at": {
      +            "description": "When the price was last reported (RFC 3339)",
      +            "type": "string"
      +          },
      +          "route_km": {
      +            "description": "Distance along the route from its start, km",
      +            "type": [
      +              "null",
      +              "number"
      +            ]
      +          },
      +          "unit": {
      +            "description": "What the price is per: L, kg or kWh",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "lat",
      +          "lon"
      +        ],
      +        "type": "object"
      +      },
      +      "type": [
      +        "null",
      +        "array"
      +      ]
      +    },
      +    "unit": {
      +      "description": "What prices are per: L, kg or kWh",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "fuel",
      +    "unit",
      +    "sort_by",
      +    "found",
      +    "returned",
      +    "prices",
      +    "stations"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the annotations (which already declare read-only, idempotent, non-destructive, open-world) by disclosing the key hidden behavior: sort_by=price only considers the 50 nearest stations inside the radius, so it is not a global cheapest search. It also gives price units per fuel family, local-currency pricing, and the ~40-country coverage with a pointer to pumperly://stats.

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?

Front-loads what the tool returns, then the input options, then the sort semantics and pricing units. Five dense sentences, each carrying distinct information with no restatement of the title or schema.

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 a 7-parameter, enum-heavy, open-world search tool with an output schema already covering return shape, the description supplies everything else an agent needs: input-mode choice, sort trade-offs and its 50-station cap, price units and currency, and geographic coverage limits.

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 genuine meaning the schema does not: the price-sort candidate cap of 50 nearest within radius, and the per-unit pricing basis (per litre, per kg for CNG/LNG/H2, per kWh for EV). It reinforces rather than replaces the schema's lat/lon vs near and limit descriptions.

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 ('Find the fuel stations or EV chargers closest to a point') plus the value-add of current prices. The point-proximity scope inherently separates it from route-based siblings (calculate_route, find_route_stations, cheapest_fuel_on_route) and from get_stations_in_area.

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?

Explains the two ways to specify a search point (lat/lon vs a geocoded `near` name) and when sort_by=price is the right choice. It never names the sibling tools or says when to prefer them (e.g. route-based search instead), so it stops short of full when/when-not guidance.

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