oecd-mcp-server

Oecd Query Dataset

oecd_query_dataset

Read-onlyIdempotent

Fetch observations from an OECD dataflow filtered by a dimension key and optional time range. Returns decoded rows (one per observation) with dimension and attribute labels, and values already scaled by the observation unit multiplier. Large multi-country time-series spill to a DataCanvas table — follow up with oecd_dataframe_query; without DataCanvas every row still comes back, but the rendered table stops at a preview slice. Call oecd_get_dataset_info first to learn the dimension order for constructing the key.

Input Schema

TableJSON Schema

Name	Required	Description
`key`	Yes	Dot-delimited dimension key matching the dimension order from oecd_get_dataset_info. Empty segments are wildcards; "+" separates multiple values per segment. Example: "A.USA+DEU.B1GQ.." — Annual, USA or Germany, GDP, all remaining dimensions.
`flow_ref`	Yes	Full flow reference — e.g. "OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I", or the bare "OECD.TAD.ARP,DF_AEI2024_DASHBOARD" form for a dataflow published without a datastructure prefix. Obtain from oecd_search_datasets and pass it through unchanged.
`canvas_id`	No	Canvas ID from a prior oecd_query_dataset call — exactly 10 characters of letters, digits, hyphens, and underscores — to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one; a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline.
`end_period`	No	End of the time range — ISO period code such as "2023" or "2023-Q4". Omit to include up to the latest available period.
`start_period`	No	Start of the time range — ISO period code such as "2010", "2010-Q1", or "2010-01". Omit to include all history (may produce very large results).

Output Schema

TableJSON Schema

Name	Required	Description
`rows`	No	Observation rows. Every row of the result when truncated is absent; the leading preview slice when truncated is true — query the canvas table for the rest.
`error`	No	Present when the call failed. Absent on success.
`source`	No	Data source attribution — always "OECD".
`canvas_id`	No	Canvas handle for the staged result. Present only when DataCanvas is configured and the result exceeded the inline budget; absent when DataCanvas is off, and absent when it is on but the result fit inline. Pass to oecd_dataframe_query or oecd_dataframe_describe.
`query_key`	No	Dimension key used in this query.
`row_count`	No	Total rows in the result (or on the canvas when truncated).
`truncated`	No	True when rows is a preview slice and the full result was staged on DataCanvas; omitted entirely (never false) when rows holds the complete result. Use oecd_dataframe_query with the canvas_id for analytics over the full set. A complete rows never means a complete rendered table — content_table_capped reports that separately.
`table_name`	No	Canvas table name holding the full result — present when canvas_id is set.
`query_flow_ref`	No	Flow reference used in this query.
`query_end_period`	No	End period filter applied in this query, if any.
`content_table_rows`	No	Rows the rendered table shows when content_table_capped is true.
`query_start_period`	No	Start period filter applied in this query, if any.
`content_table_capped`	No	True when the rendered table shows only the leading rows of the result. Distinct from truncated: nothing was staged anywhere, and structuredContent.rows still holds every row. To shrink the result itself, name fewer values per key segment or set a narrower start_period / end_period; to reach the full set as a queryable table instead, run with CANVAS_PROVIDER_TYPE=duckdb and follow up with oecd_dataframe_query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 20, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID from a prior oecd_query_dataset call, to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one — a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline."New value: +"Canvas ID from a prior oecd_query_dataset call — exactly 10 characters of letters, digits, hyphens, and underscores — to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one; a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

First observedSep 1, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already cover readOnly/openWorld/idempotent, so the bar is lower. The description still adds meaningful behavior: decoded rows with labels, values scaled by the observation unit multiplier, and the large-result spill to DataCanvas with a preview slice when DataCanvas is absent. These details go beyond the annotations and help an agent understand side effects and result handling. No contradiction with annotations.

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?

Three sentences with no filler: purpose, return behavior and spill edge case, and a necessary prerequisite. Every sentence contributes new information and the most important facts come first. This is appropriately compact for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core call, return shape, spill behavior, and the critical dimension-order prerequisite. With an output schema present and full schema parameter documentation, the remaining gaps (e.g., exact period formats, error cases) are already covered structurally. It is complete enough for correct invocation, though it doesn't discuss pagination or error scenarios in free text.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description itself adds only cross-reference guidance (use oecd_get_dataset_info to learn dimension order), not extra semantics for the parameters. The schema's own descriptions already cover key syntax, flow_ref forms, canvas_id rules, and period formats. This does not meaningfully exceed the baseline.

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 first sentence clearly states a specific action—fetch observations from an OECD dataflow—and the filtering mechanism (dimension key, optional time range). It distinguishes itself from siblings like oecd_dataframe_query (which queries the spilled DataCanvas table) and oecd_get_dataset_info (which returns metadata). No ambiguity about what this tool does.

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 explicit context: 'Call oecd_get_dataset_info first to learn the dimension order for constructing the key' and explains the spill behavior with a follow-up to oecd_dataframe_query. It does not explicitly enumerate when to avoid this tool in favor of other siblings, but the prerequisite and follow-up guidance are clear. This fits 'clear context, no exclusions.'

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

All oecd-mcp-server tools Inspect

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.