Skip to main content
Glama

eurostat-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Get Eurostat Dimension Values

eurostat_get_dimension_values
Read-onlyIdempotent

List the valid values for a specific dimension in a Eurostat dataset (e.g., all unit codes for nama_10_gdp, all geo codes for a regional dataset). Use this when eurostat_get_dataset_info returns more values than the 10-item sample, or to confirm exact codes before querying. For the "geo" dimension, use geo_level to filter by NUTS hierarchy (country, nuts1, nuts2, nuts3). An invalid code matches nothing: eurostat_query_dataset names it in unmatchedValues, or in its no_results error when the query matched nothing at all, and Eurostat rejects it as a fault on eurostat_download_dataset; use this tool to verify codes first. At most 2,000 values come back inline — a longer list, such as the 37,069 CN8 product codes of DS-045409 or a daily time dimension, is cut there and says so. Pass canvas_id to also stage the whole list, whatever its length, as a two-column code/label table on that dataframe canvas: search it with SQL, or join it to a eurostat_download_dataset table, whose columns carry dimension codes only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
canvas_idNoAlso stage the values on this dataframe canvas as a table with two columns, code and label, holding every value the dimension lists — past the inline cap too — at the geo_level requested, country when it is omitted. Pass the canvasId a eurostat_download_dataset or eurostat_query_dataset response returned, then search the staged table with SQL or join it to a download on the dimension column (e.g., d.geo = g.code). Omit to return the values inline only: this tool never starts a canvas. Ignored on deployments without a dataframe canvas.
dimensionYesDimension code to retrieve values for (e.g., "unit", "na_item", "geo"). Use eurostat_get_dataset_info to see available dimensions.
geo_levelNoNUTS hierarchy level filter — applies only when dimension is "geo"; passing it with any other dimension is rejected. Options: "aggregate" (EU/EA codes), "country" (2-letter codes, default), "nuts1" (3-char), "nuts2" (4-char), "nuts3" (5-char).
dataset_codeYesDataset code (e.g., "nama_10_gdp", or "DS-045409" for a Comext collection).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe inline cap applied. Present alongside truncated.
errorNoPresent when the call failed. Absent on success.
shownNoValues returned inline. Present alongside truncated.
noticeNoWhere the values past the inline cap are: the staged table when canvas_id was passed, or how to stage them. Present alongside truncated.
valuesNoDataset-available values for this dimension, in Eurostat's order — for geo, the subset at geoLevel. Holds every value up to 2,000; past that, the first 2,000, with truncated set and the whole list on the canvas table when canvas_id was passed.
canvasIdNoDataframe canvas the values were staged on — the canvas_id supplied. Omitted when nothing was staged: canvas_id was omitted, this deployment runs without a dataframe canvas, or the dimension lists no values.
geoLevelNoEffective NUTS hierarchy level for the geo value set. Present only for the geo dimension; country is reported when geo_level was omitted.
tableNameNoCanvas table holding every value as two VARCHAR columns, code and label. Call eurostat_dataframe_describe with canvasId first to confirm it, then join it in eurostat_dataframe_query. Omitted alongside canvasId.
truncatedNoTrue when the dimension lists more values than the inline cap and values holds only the first of them. Omitted when values holds every one.
totalCountNoNumber of distinct values the dimension lists, after geoLevel filtering for geo — all of them, including any past the inline cap.
dimensionCodeNoThe dimension code that was queried.
dimensionLabelNoHuman-readable dimension name.
stagedRowCountNoRows written to the canvas table. Equals totalCount. Omitted alongside tableName.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • addedInput schema / properties / canvas_id
      Added value: +{
+  "description": "Also stage the values on this dataframe canvas as a table with two columns, code and label, holding every value the dimension lists — past the inline cap too — at the geo_level requested, country when it is omitted. Pass the canvasId a eurostat_download_dataset or eurostat_query_dataset response returned, then search the staged table with SQL or join it to a download on the dimension column (e.g., d.geo = g.code). Omit to return the values inline only: this tool never starts a canvas. Ignored on deployments without a dataframe canvas.",
+  "pattern": "^[A-Za-z0-9_-]{10}$",
+  "type": "string"
+}
    • changedInput schema / properties / dataset_code / description
      Previous value: -"Dataset code (e.g., \"nama_10_gdp\")."New value: +"Dataset code (e.g., \"nama_10_gdp\", or \"DS-045409\" for a Comext collection)."
    • addedOutput schema / properties / canvasId
      Added value: +{
+  "description": "Dataframe canvas the values were staged on — the canvas_id supplied. Omitted when nothing was staged: canvas_id was omitted, this deployment runs without a dataframe canvas, or the dimension lists no values.",
+  "type": "string"
+}
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The inline cap applied. Present alongside truncated.",
+  "type": "number"
+}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code or dimension code does not exist. `async_response`: Eurostat returned an asynchronous-response condition. `no_results`: The dataset has no geo values at the effective geo_level. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code or dimension code does not exist. `no_results`: The dataset has no geo values at the effective geo_level. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. `upstream_fault`: Eurostat returned a dataset structure or content constraint this server cannot read: malformed, truncated, not XML, or missing the requested dataset's dataflow. `canvas_not_found`: A canvas_id was supplied for staging but is unknown or its lifetime has elapsed. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "not_found",
-  "async_response",
-  "no_results",
-  "conflicting_params"
-]New value: +[
+  "not_found",
+  "no_results",
+  "conflicting_params",
+  "upstream_fault",
+  "canvas_not_found"
+]
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Where the values past the inline cap are: the staged table when canvas_id was passed, or how to stage them. Present alongside truncated.",
+  "type": "string"
+}
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Values returned inline. Present alongside truncated.",
+  "type": "number"
+}
    • addedOutput schema / properties / stagedRowCount
      Added value: +{
+  "description": "Rows written to the canvas table. Equals totalCount. Omitted alongside tableName.",
+  "type": "number"
+}
    • addedOutput schema / properties / tableName
      Added value: +{
+  "description": "Canvas table holding every value as two VARCHAR columns, code and label. Call eurostat_dataframe_describe with canvasId first to confirm it, then join it in eurostat_dataframe_query. Omitted alongside canvasId.",
+  "type": "string"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of distinct values returned, after geoLevel filtering for geo."New value: +"Number of distinct values the dimension lists, after geoLevel filtering for geo — all of them, including any past the inline cap."
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the dimension lists more values than the inline cap and values holds only the first of them. Omitted when values holds every one.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / values / description
      Previous value: -"All dataset-available values for this dimension. For geo, this is the subset at geoLevel."New value: +"Dataset-available values for this dimension, in Eurostat's order — for geo, the subset at geoLevel. Holds every value up to 2,000; past that, the first 2,000, with truncated set and the whole list on the canvas table when canvas_id was passed."
  2. Changed5 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code or dimension code does not exist. `async_response`: Eurostat returned an async warning — the dimension query matched too many observations. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The dataset code or dimension code does not exist. `async_response`: Eurostat returned an asynchronous-response condition. `no_results`: The dataset has no geo values at the effective geo_level. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "not_found",
-  "async_response",
-  "conflicting_params"
-]New value: +[
+  "not_found",
+  "async_response",
+  "no_results",
+  "conflicting_params"
+]
    • addedOutput schema / properties / geoLevel
      Added value: +{
+  "description": "Effective NUTS hierarchy level for the geo value set. Present only for the geo dimension; country is reported when geo_level was omitted.",
+  "enum": [
+    "aggregate",
+    "country",
+    "nuts1",
+    "nuts2",
+    "nuts3"
+  ],
+  "type": "string"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total number of distinct values returned."New value: +"Total number of distinct values returned, after geoLevel filtering for geo."
    • changedOutput schema / properties / values / description
      Previous value: -"All valid values for this dimension in the dataset."New value: +"All dataset-available values for this dimension. For geo, this is the subset at geoLevel."
  3. 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": [
+      "dimensionCode",
+      "dimensionLabel",
+      "values",
+      "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: `not_found`: The dataset code or dimension code does not exist. `async_response`: Eurostat returned an async warning — the dimension query matched too many observations. `conflicting_params`: geo_level was combined with a dimension other than \"geo\", where it has no effect. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "async_response",
+            "conflicting_params"
+          ],
+          "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: -[
-  "dimensionCode",
-  "dimensionLabel",
-  "values",
-  "totalCount"
-]
  4. Changed1 schema field changed
    • changedOutput schema / properties / values / items / properties / code / description
      Previous value: -"Dimension value code. Use these as filter values in eurostat_query_dataset."New value: +"Dimension value code. Use these as filter values in eurostat_query_dataset and eurostat_download_dataset."
  5. Changed1 schema field changed
    • changedInput schema / properties / geo_level / description
      Previous value: -"NUTS hierarchy level filter — only relevant when dimension is \"geo\". Options: \"aggregate\" (EU/EA codes), \"country\" (2-letter codes, default), \"nuts1\" (3-char), \"nuts2\" (4-char), \"nuts3\" (5-char)."New value: +"NUTS hierarchy level filter — applies only when dimension is \"geo\"; passing it with any other dimension is rejected. Options: \"aggregate\" (EU/EA codes), \"country\" (2-letter codes, default), \"nuts1\" (3-char), \"nuts2\" (4-char), \"nuts3\" (5-char)."
  6. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already carry readOnlyHint/idempotentHint/openWorldHint. On top of that the description discloses non-obvious behavior: the 2,000-value inline cap with truncation notice, that canvas_id staging captures the full list past the cap, and that this tool never starts a canvas. This adds genuine value beyond structured fields; only near-exhaustive detail keeps it from a 5.

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?

Front-loaded with purpose, then usage, then behavioral constraints; every sentence earns its place. It is slightly dense and the geo-level detail partly duplicates schema text, but no sentence is filler and the logical ordering (why, when, constraints, side-effects) is strong.

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?

Thorough for a complex tool with 4 params and an output schema: covers error-propagation paths into query/download siblings, the truncation policy, the staging/join workflow, and the geo filtering constraint. Nothing an agent needs to decide between inline vs canvas use or to handle long lists 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 meaningfully extends the schema: it explains the canvas_id staging interplay with the inline cap, the geo_level rejection when applied to non-geo dimensions, and the default geo_level of 'country'. These go beyond what the schema states.

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?

Begins with a specific verb+resource ('List the valid values for a specific dimension in a Eurostat dataset') with concrete examples (unit codes for nama_10_gdp, geo codes). It clearly distinguishes itself from eurostat_get_dataset_info (10-item sample) via explicit contrast, so an agent can tell them apart without opening the 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?

Gives explicit when-to-use triggers: when get_dataset_info returns more than its 10-item sample, or to confirm exact codes before querying. It also names the downstream consequences of invalid codes across siblings (unmatchedValues in query_dataset, fault on download_dataset) and routes the agent to this tool to verify first, fully resolving alternative selection.

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

All eurostat-mcp-server toolsInspect
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