Skip to main content
Glama

Fuel or EV stations in an area

get_stations_in_area
Read-onlyIdempotent

Lists fuel stations or EV chargers within a bounding box, returning current prices and min/median/max per currency, price-sorted by default for area comparisons.

Instructions

List the fuel stations or EV chargers inside a bounding box with current prices, cheapest first by default, plus the min, median and max price per currency. Use it for "cheapest diesel in this town". For a point and radius use find_nearest_stations; along a trip use cheapest_fuel_on_route. Prices are per litre (per kg for CNG, LNG and H2, per kWh for EV) in local currency. Keep the box city-sized: a whole-country box can exceed the 8 MB answer cap.

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

Input Schema

NameRequiredDescriptionDefault
bboxYesBounding box as "minLon,minLat,maxLon,maxLat" in decimal degrees, longitude first. Example for central Madrid: "-3.75,40.38,-3.65,40.45".
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.
limitNoHow many stations to return, 1 to 100. Default 20.
sort_byNoprice (cheapest first, default) or distance (from the centre of the box).price

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. Changed8 schema fields changedv0.2.1
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / bbox / description
      Previous value: -"Bounding box as \"minLon,minLat,maxLon,maxLat\""New value: +"Bounding box as \"minLon,minLat,maxLon,maxLat\" in decimal degrees, longitude first. Example for central Madrid: \"-3.75,40.38,-3.65,40.45\"."
    • addedInput schema / properties / bbox / pattern
      Added value: +"^\\s*-?\\d+(\\.\\d+)?\\s*,\\s*-?\\d+(\\.\\d+)?\\s*,\\s*-?\\d+(\\.\\d+)?\\s*,\\s*-?\\d+(\\.\\d+)?\\s*$"
    • 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"
      +]
    • addedInput schema / properties / limit
      Added value: +{
      +  "default": 20,
      +  "description": "How many stations to return, 1 to 100. Default 20.",
      +  "maximum": 100,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / sort_by
      Added value: +{
      +  "default": "price",
      +  "description": "price (cheapest first, default) or distance (from the centre of the box).",
      +  "enum": [
      +    "price",
      +    "distance"
      +  ],
      +  "type": "string"
      +}
    • 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.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral content: default sort order, the aggregate min/median/max per currency returned alongside results, the price unit per fuel family (litre, kg for CNG/LNG/H2, kWh for EV), and the 8 MB answer cap with the box-size advice that avoids it. The size cap is a non-obvious failure mode disclosed up front.

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 routing alternatives, then unit semantics, then the size constraint — each sentence carries distinct information with no repetition of schema or annotations.

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?

Output schema exists so return values need no explanation, yet the description still flags the aggregate fields and the cap that affects result completeness. For a 4-parameter read tool with full schema coverage, nothing an agent needs in order to call it correctly 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 earns more by explaining that prices are quoted per litre, per kg for CNG/LNG/H2 and per kWh for EV, which is unit semantics the schema only points to indirectly. It does not restate the bbox format or limit bounds, which the schema already handles well.

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 ('List the fuel stations or EV chargers inside a bounding box') and immediately names the two nearest siblings (find_nearest_stations, cheapest_fuel_on_route) with the geometric condition that selects each. An agent can route between all three without opening a schema.

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?

Explicit when-to-use ('cheapest diesel in this town'), plus explicit alternatives for the two adjacent cases: point-and-radius and along-a-trip. It also gives a when-not constraint ('keep the box city-sized'). Nothing is left to inference.

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