sdmx-data-mcp

get_data

Retrieve actual observations from SDMX dataflows as structured records. Use filters and limits to control the result size, and read the response for truncation and fallback details.

Instructions

Retrieve observations as records. This returns the actual numbers.

Call inspect_dataflow first to confirm component and code IDs and to check the size of what you are about to pull.

If a TIME_PERIOD clause is rejected by the service, it is retried without that clause and the cutoff is applied locally; the response says so in filter_fallback.

Returns: The observations, the filter actually sent, and a truncated flag. When truncated, the rows are the first N in service order and are NOT a representative sample.

Raises: ToolError: If retrieval fails. The message carries a [kind] discriminator and a retry hint.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ref`	Yes	Dataflow reference in agency:id(version) form, such as 'BIS:WS_CBS_PUB(1.0)'.
`limit`	No	Maximum rows to return. Defaults to 1000, hard ceiling 10000.
`labels`	No	'id' returns code IDs (default, and far more compact). 'name' substitutes human-readable names. 'both' gives 'ID: Name'. Leave as 'id' unless names were requested.	id
`columns`	No	Components to return, such as ['OBS_VALUE']. Omit for all. TIME_PERIOD and SERIES_KEY are added automatically by pysdmx.
`filters`	No	Filter selecting the data, such as "L_MEASURE = 'S' AND L_REP_CTY = 'CH' AND TIME_PERIOD >= '2020-Q1'". AND only, never OR; use IN ('A', 'B') for several values of one component. Omitting this pulls the whole dataflow and will almost certainly truncate.
`service`	No	Service name or SDMX-REST v2 base URL.

Output Schema

TableJSON Schema

Name	Required	Description
`ref`	Yes	The resolved dataflow reference.
`columns`	Yes
`records`	Yes
`service`	Yes
`next_step`	Yes
`row_count`	Yes	Rows actually returned.
`truncated`	Yes	True when total_rows_available exceeded the cap. The returned rows are the first row_count in service order and are NOT a representative sample - narrow the filter for a complete answer.
`filter_applied`	Yes	The filter actually sent to the service, echoed so the caller can verify what was queried.
`filter_fallback`	No	Set when server-side time pushdown failed and the time constraint was applied locally instead. Names the filter that was sent and the cutoff applied with pandas.
`total_rows_available`	Yes	Rows matching the filter before the cap was applied.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden. It discloses the fallback behavior for rejected TIME_PERIOD clauses, the truncated flag and that rows are 'NOT a representative sample' when truncated, and the ToolError format with a [kind] discriminator and retry hint. It also notes that TIME_PERIOD and SERIES_KEY are added automatically. This is thorough behavioral disclosure.

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?

The description is moderately long but every sentence earns its place. It is front-loaded with the purpose, then proceeds logically to prerequisites, fallback behavior, return info, and error handling. It is structured and does not ramble, though it could be slightly trimmed without losing information.

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?

Given the tool's complexity (6 params, output schema exists, no annotations), the description covers the critical gotchas: prerequisite inspection, fallback behavior, truncation semantics, and error format. It does not need to explain return values because an output schema is present. Nothing essential for correct invocation 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 adds value by contextualizing the ref and filters parameters—telling the agent to obtain component/code IDs from inspect_dataflow and explaining the consequence of omitting filters. This goes beyond the schema's per-parameter descriptions, hence a 4.

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 'Retrieve observations as records. This returns the actual numbers.' which is a specific verb+resource that clearly distinguishes this from the sibling tools (list_services, search_dataflows, inspect_dataflow). It leaves no ambiguity about what the tool does and its output nature.

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?

It explicitly instructs the agent to 'Call inspect_dataflow first to confirm component and code IDs and to check the size of what you are about to pull.' This is a clear prerequisite and directly routes the agent to the right sibling. It also warns that omitting the filters 'pulls the whole dataflow and will almost certainly truncate,' giving concrete guidance on when to use filters.

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

Deploy Server