Skip to main content
Glama

Query Eurostat Dataframes

eurostat_dataframe_query
Read-onlyIdempotent

Run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas, reaching observations beyond an inline preview and aggregating or joining tables without re-fetching Eurostat. Call eurostat_dataframe_describe first for table and column names. Only a single SELECT runs: statement chaining, non-SELECT verbs, and functions reading files or external data are rejected. Columns are flat: dimension codes, obs_value, obs_flag / obs_flag_label, and conf_status / conf_status_label. Tables eurostat_query_dataset staged also carry dimension _label companions; DS-* tables also carry obs_value_text for published text values. Join observation tables on dimension codes and time. A staged dimension value list has code and label columns; join it to an observation dimension code to add labels. Returns every complete row the canvas supplies, bounded only by the canvas row limit; nested cells render as lossless JSON. A row-limit cut sets truncated and adds a notice: page the same deterministic SELECT over unchanged tables with a total ORDER BY and LIMIT/OFFSET, advancing by actual rowCount. Restart an unordered first page sorted at offset zero; tied keys need tie-breakers. Volatile SQL and changing or expired tables cannot provide stable paging.

Input Schema

NameRequiredDescriptionDefault
sqlYesA single read-only SELECT statement. Reference tables by the names eurostat_dataframe_describe reports. Example: SELECT geo, geo_label, AVG(obs_value) AS mean FROM df_a1b2c3d4 WHERE time >= '2020' GROUP BY geo, geo_label ORDER BY mean DESC.
canvas_idYesCanvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables.

Output Schema

NameRequiredDescriptionDefault
rowsNoComplete result rows, keyed by column name, bounded by the canvas row limit. Nested cells render as JSON; 64-bit integers arrive as strings so they survive intact. Cast to DOUBLE in SQL if a number is wanted.
errorNoPresent when the call failed. Absent on success.
noticeNoWhole-row cut disclosure and deterministic SQL paging guidance. Omitted when no rows were omitted.
columnsNoColumn names in projection order.
canvasIdNoCanvas identifier the query ran against.
rowCountNoComplete rows returned after the canvas row limit. Advance SQL OFFSET by this actual count.
truncatedNoTrue when the canvas row limit omitted rows. Follow notice for SQL paging.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedOutput schema / properties / rowCount / description
      Previous value: -"Complete rows returned after the canvas row limit and the 64,000-byte budget per serialized response surface. Advance SQL OFFSET by this actual count."New value: +"Complete rows returned after the canvas row limit. Advance SQL OFFSET by this actual count."
    • changedOutput schema / properties / rows / description
      Previous value: -"Complete result rows, keyed by column name, bounded by the canvas row limit and 64,000 bytes per serialized surface. Nested cells render as JSON; 64-bit integers arrive as strings so they survive intact. Cast to DOUBLE in SQL if a number is wanted."New value: +"Complete result rows, keyed by column name, bounded by the canvas row limit. Nested cells render as JSON; 64-bit integers arrive as strings so they survive intact. Cast to DOUBLE in SQL if a number is wanted."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the canvas row limit or the 64,000-byte budget per serialized response surface omitted rows. At least one complete row is retained even if oversized. Follow notice for SQL paging."New value: +"True when the canvas row limit omitted rows. Follow notice for SQL paging."
  2. Changed4 schema fields changed
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Whole-row cut disclosure and deterministic SQL paging guidance. Omitted when no rows were omitted.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / rowCount / description
      Previous value: -"Rows materialized into this response. Equals the full result size unless truncated is true."New value: +"Complete rows returned after the canvas row limit and the 64,000-byte budget per serialized response surface. Advance SQL OFFSET by this actual count."
    • changedOutput schema / properties / rows / description
      Previous value: -"Result rows, each keyed by column name. Bounded by the canvas row limit. 64-bit integer results — COUNT(*) among them — arrive as strings so values outside the JSON number range survive intact; cast to DOUBLE in the SQL if a number is wanted."New value: +"Complete result rows, keyed by column name, bounded by the canvas row limit and 64,000 bytes per serialized surface. Nested cells render as JSON; 64-bit integers arrive as strings so they survive intact. Cast to DOUBLE in SQL if a number is wanted."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the result exceeded the canvas row limit and was cut short. Add a LIMIT, an aggregate, or a narrower WHERE clause to see the rest."New value: +"True when the canvas row limit or the 64,000-byte budget per serialized response surface omitted rows. At least one complete row is retained even if oversized. Follow notice for SQL paging."
  3. Changed1 schema field changed
    • changedInput schema / properties / canvas_id / description
      Previous value: -"Canvas identifier returned as canvasId by eurostat_query_dataset or eurostat_download_dataset. Identifies the workspace holding the staged tables."New value: +"Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables."
  4. Changed2 schema fields changed
    • removedInput schema / properties / canvas_id / minLength
      Removed value: -1
    • addedInput schema / properties / canvas_id / pattern
      Added value: +"^[A-Za-z0-9_-]{10}$"
  5. 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": [
      +      "canvasId",
      +      "columns",
      +      "rows",
      +      "rowCount",
      +      "truncated"
      +    ]
      +  },
      +  {
      +    "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: `canvas_disabled`: This deployment runs without a dataframe canvas, so there is nothing to query. `canvas_not_found`: The canvas_id is unknown or its lifetime has elapsed. `missing_table`: The SQL names a table that is not staged on this canvas, or that has expired. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "canvas_disabled",
      +            "canvas_not_found",
      +            "missing_table"
      +          ],
      +          "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: -[
      -  "canvasId",
      -  "columns",
      -  "rows",
      -  "rowCount",
      -  "truncated"
      -]
  6. Changed1 schema field changed
    • changedInput schema / properties / canvas_id / description
      Previous value: -"Canvas identifier returned by eurostat_query_dataset as canvasId. Identifies the workspace holding the staged tables."New value: +"Canvas identifier returned as canvasId by eurostat_query_dataset or eurostat_download_dataset. Identifies the workspace holding the staged tables."
  7. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: only a single SELECT runs, statement chaining and non-SELECT verbs and external-reading functions are rejected. It also discloses the flat column layout, label companions, the join key guidance, truncation flags and notices, and the exact paging contract with the caveat that volatile or expired tables cannot page stably.

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?

Purpose and the describe prerequisite are front-loaded, and nearly every sentence carries behavioral content (limits, columns, joins, paging). The closing paging passage is dense and run-on, requiring careful parsing, which slightly hurts readability but not correctness.

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 two-parameter SQL tool with an output schema, the description covers everything an agent needs: what runs, what is rejected, how tables are named and shaped, how to join, and how row-limit truncation and paging behave. Nothing material is left to inference.

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 adds real meaning by constraining the sql parameter to a single SELECT referencing describe-reported table names and by identifying affected tables as canvas-staged workspaces tied to canvas_id. It stops short of format or syntax detail beyond the schema example.

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: run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas. It distinguishes itself from the fetch-oriented siblings by framing the value as reaching observations beyond an inline preview and aggregating/joining without re-fetching Eurostat.

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?

Gives a clear prerequisite (call eurostat_dataframe_describe first for table and column names) and an implicit alternative (re-fetching via Eurostat instead of querying staged tables). It does not explicitly name a sibling to use instead in any scenario, so it falls short of full when/when-not routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.