Skip to main content
Glama

openchargemap-mcp-server

by io.github.cyanheads

openchargemap-mcp-server: lookup reference

openchargemap_lookup_reference
Read-onlyIdempotent

Resolve Open Charge Map reference data to the integer IDs that openchargemap_find_stations filters require. Pick a category and pass a name or code to resolve — "CCS" or "Tesla Supercharger" -> a connectiontypeid, "ChargePoint" -> an operatorid, "Public - Pay At Location" -> a usagetypeid, "France" or "FR" -> a country. Omit the query to browse the whole category. Large categories come back one page at a time: when a page reports truncated, repeat the call with the reported nextOffset to read the next one.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum entries to return when browsing or when a query matches several. Max 100.
queryNoName, title, code, or alias to resolve (e.g. "CCS", "CHAdeMO", "Tesla", "Public", "France", "FR"). Case-insensitive, matches on title, formal name, and known aliases. Omit to browse the entire category.
offsetNoEntries to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Applies to browsing and to a query with many matches alike; the order is stable, so every entry is reachable by paging.
categoryYesWhich reference set to query. connectiontypes -> connectiontypeid; operators -> operatorid; usagetypes -> usagetypeid; statustypes -> statustypeid; currenttypes -> current type; levels -> charge level (1/2/3); countries -> ISO country.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoEntries in the returned page.
noticeNoHow to reach the entries this page left out.
sourceNoWhere these entries came from. "live" — a startup refresh from Open Charge Map returned a complete set and is what is being served. "bundled" — the snapshot shipped with the server is being served, either because the refresh is switched off or because it failed and the server fell back to the bundle.
matchesNoMatching reference entries, best/exact match first.
categoryNoThe reference category queried.
truncatedNoTrue when matching entries were left out of the returned page.
nextOffsetNoThe offset to pass on an otherwise identical call to read the next page. Absent on the last page.
totalCountNoEntries matching before the offset/limit page was taken — the whole category when browsing, every match when a query was given.
attributionNoRequired CC BY 4.0 attribution to Open Charge Map contributors.
filterParamNoThe find_stations input parameter these IDs feed (e.g. "connectiontypeid"). Omitted for categories with no direct filter (currenttypes; countries use countrycode).
snapshotDateNoDate the reference data in this response was captured, so callers know its vintage — the day the live refresh ran when source is "live", the bundled snapshot's own capture date when source is "bundled". Read it together with source: the same date can mean either a fresh fetch or a freshly cut bundle.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "category",
+      "matches",
+      "snapshotDate",
+      "source",
+      "attribution",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_match`: No reference entry in the category matched the query. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_match"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "category",
-  "matches",
-  "snapshotDate",
-  "source",
-  "attribution",
-  "totalCount"
-]
  2. Changed9 schema fields changed
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "Entries to skip before the returned page, for reading past a truncated result. Repeat the same call with the nextOffset value the previous one reported. Applies to browsing and to a query with many matches alike; the order is stable, so every entry is reachable by paging.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedOutput schema / properties / nextOffset
      Added value: +{
+  "description": "The offset to pass on an otherwise identical call to read the next page. Absent on the last page.",
+  "type": "number"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"How to reach the entries beyond the cap when a browse was capped."New value: +"How to reach the entries this page left out."
    • changedOutput schema / properties / shown / description
      Previous value: -"Number of entries returned when the cap was hit."New value: +"Entries in the returned page."
    • changedOutput schema / properties / snapshotDate / description
      Previous value: -"Date the bundled reference snapshot was captured, so callers know the data vintage."New value: +"Date the reference data in this response was captured, so callers know its vintage — the day the live refresh ran when source is \"live\", the bundled snapshot's own capture date when source is \"bundled\". Read it together with source: the same date can mean either a fresh fetch or a freshly cut bundle."
    • addedOutput schema / properties / source
      Added value: +{
+  "description": "Where these entries came from. \"live\" — a startup refresh from Open Charge Map returned a complete set and is what is being served. \"bundled\" — the snapshot shipped with the server is being served, either because the refresh is switched off or because it failed and the server fell back to the bundle.",
+  "enum": [
+    "live",
+    "bundled"
+  ],
+  "type": "string"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of entries returned."New value: +"Entries matching before the offset/limit page was taken — the whole category when browsing, every match when a query was given."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when a browse was capped at limit."New value: +"True when matching entries were left out of the returned page."
    • changedOutput schema / required
      Previous value: -[
-  "category",
-  "matches",
-  "snapshotDate",
-  "attribution",
-  "totalCount"
-]New value: +[
+  "category",
+  "matches",
+  "snapshotDate",
+  "source",
+  "attribution",
+  "totalCount"
+]
  3. Changed3 schema fields changed
    • removedInput schema / properties / query / minLength
      Removed value: -1
    • addedInput schema / properties / query / pattern
      Added value: +"\\S"
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when a query matched nothing."New value: +"How to reach the entries beyond the cap when a browse was capped."
  4. Changed2 schema fields changed
    • changedOutput schema / properties / matches / description
      Previous value: -"Matching reference entries, best/exact match first. Use the id in a find_stations filter."New value: +"Matching reference entries, best/exact match first."
    • changedOutput schema / properties / matches / items / properties / id / description
      Previous value: -"The reference ID — pass to the matching openchargemap_find_stations filter (e.g. connectiontypeid)."New value: +"The reference ID for this entry."
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral detail beyond that: it explains the query matching is case-insensitive and matches aliases, describes pagination behavior ('Large categories come back one page at a time'), and instructs the agent to follow nextOffset for subsequent pages. It also clarifies that offset skips entries and the order is stable. These are valuable runtime behaviors not inferable from annotations alone.

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?

The description is a single, dense paragraph with no filler. Every sentence serves a purpose: purpose statement, category-to-ID mapping examples, browsing instruction, and pagination handling. The most important information (what it resolves and for whom) is front-loaded. It is appropriately concise for the tool's 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?

The tool has an output schema (so return format is externally defined), annotations cover safety and idempotency, and the description explains all operational nuances: category semantics, query behavior, pagination, and offset usage. There is nothing missing that an agent would need to correctly invoke this tool, even for large reference sets. The combination of schema, annotations, and description is complete.

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 provides 100% coverage with descriptive parameter descriptions (e.g., category enum values mapped to ID types, query pattern and alias matching). The description enhances this by giving concrete examples ('CCS' -> connectiontypeid, 'ChargePoint' -> operatorid) and explaining the relationship between offset and nextOffset for paging. This goes beyond the schema's baseline, but since the schema is already thorough, the added value is an incremental improvement rather than a necessity.

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: 'Resolve Open Charge Map reference data to the integer IDs that openchargemap_find_stations filters require.' It names the consumer tool and explicitly differentiates itself from siblings (find_stations is the target, get_station and get_station_comments are unrelated). The mapping examples further clarify the exact role.

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, actionable usage context: pick a category, pass a name/code to get an ID, or omit the query to browse. It also explains pagination for large categories. However, it does not explicitly state when not to use this tool versus alternatives (e.g., 'use this only for reference lookups, not station details'), though the purpose statement makes that inference straightforward. Is it explicit enough for a 5? It names the dependent tool, so it effectively guides selection, but the lack of an explicit exclusion directive keeps it at 4.

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

All openchargemap-mcp-server toolsInspect
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/5.0
Disambiguation5/5

Each tool has a distinct role: discovery (find_stations), retrieval (get_station), community feedback (get_station_comments), and reference lookup (lookup_reference). No two tools overlap in purpose, and the descriptions reinforce their boundaries.

Naming Consistency5/5

All tool names share the 'openchargemap_' prefix followed by a clear verb_noun pattern (find_stations, get_station, get_station_comments, lookup_reference). The naming is uniform and predictive, making it easy for an agent to infer function.

Tool Count5/5

With 4 tools, the server is focused and well-scoped for a read-only EV charging station registry. Each tool serves an essential query need (search, detail, comments, reference data) without unnecessary clutter.

Completeness5/5

The tool set covers the full lifecycle of querying station data: resolving reference IDs via lookup_reference, searching with filters, retrieving detailed records, and accessing community feedback. This is complete for the stated purpose, with no obvious dead ends.

Resources