Tools

Five discovery and data tools plus two SQL analytics tools for large query results:

oecd_list_agencies

Entry point for discovery — enumerate OECD's statistical departments before searching.

• Returns agency IDs (e.g. OECD.SDD.NAD, OECD.ELS.SPD, OECD.EDU.IMEP) and dataflow counts
• Each agency carries the name of its directorate — OECD.CTP.TPS is the Centre for Tax Policy and Administration, OECD.SDD.NAD the Statistics and Data Directorate — so a department can be picked without decoding the identifier
• Publishers outside OECD that ship dataflows through the same catalog (ESTAT, IAEG-SDGs) carry no directorate
• Useful for scoping oecd_search_datasets by department (national accounts, labour, education, etc.)

oecd_search_datasets

Search the full catalog of 1,500+ OECD dataflows by keyword or department.

• Token-matching across dataflow names and descriptions — reaches datasets whose name never carries the term, so inflation returns Economic Outlook 119 and poverty returns Income inequality - Regions
• Each result reports matched_in (name, description, or both) and a plain-text description trimmed to 240 characters
• Optional agency_id filter scopes results to a specific statistical department
• limit (1–100) and offset page through the match list; total_matches reports the full count
• Returns flow_ref values (e.g. OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I) — pass directly to oecd_get_dataset_info or oecd_query_dataset. A handful of dataflows are catalogued without a datastructure prefix and come back in the bare {agencyID},{df_id} form (OECD.TAD.ARP,DF_AEI2024_DASHBOARD); both forms are accepted everywhere a flow_ref is
• Fetches and filters in-memory; the full catalog is ~5.9 MB and bounded (OECD adds datasets weekly, not continuously)

oecd_get_dataset_info

Inspect a dataflow's structure before querying.

• Returns all dimensions in key order (position 1, 2, 3 …) — dimension order is required to construct the dot-delimited key for oecd_query_dataset
• Each dimension carries its concept name from the datastructure's concept scheme, so INSTR_ASSET reads as "Financial instruments and non-financial assets" rather than repeating the id. A dimension the scheme does not cover keeps the id
• Shows codelist references for each dimension — pass to oecd_get_dimension_values to resolve human-readable names to SDMX codes
• Surfaces NonProductionDataflow flag — marks experimental or deprecated dataflows
• Resolves a flow_ref whose id prefix names no datastructure of its own by asking the dataflow for its structure — OECD.CFE.EDS,DSD_REG_LAB@DF_RATES is backed by DSD_REG_LABOUR, and answers here rather than reporting the dataflow as missing
• Required before calling oecd_query_dataset on an unfamiliar dataflow

oecd_get_dimension_values

Resolve human-readable names (countries, measures) to SDMX codes.

• Returns code + label pairs for a single dimension (e.g. REF_AREA → USA/United States, DEU/Germany)
• query matches a case-insensitive substring against both the code and its label, so PA and percent each reach PA / Percent per annum
• limit (1–500, default 50) and offset page the matching list. Both client surfaces carry the same page, so a 1,164-code dimension like UNIT_MEASURE no longer ships 66 KB of pairs to structuredContent to find one code
• When matches remain beyond the page, the response reports the full match count and how to reach the rest

oecd_query_dataset

Fetch observations from an OECD dataflow filtered by dimension key and time range.

• Accepts a dot-delimited key (e.g. A.USA+DEU.B1GQ_R.PC.) where empty segments are wildcards and + separates multiple values
• Optional start_period / end_period bound the time range (ISO format: 2010, 2010-Q1)
• Decodes SDMX-JSON index notation (0:0:2:3:0) into human-readable row objects with dimension labels
• Observation attributes (UNIT_MULT, OBS_STATUS, PRICE_BASE, DECIMALS, …) each become their own column, so an estimated or break-flagged point is distinguishable from a confirmed one
• value arrives already multiplied by the observation's UNIT_MULT — a GDP figure OECD publishes as 26054.614 billions comes back as 26054614000000. Every row carries value_scale, the power of ten applied; divide by it for the figure as OECD published it
• Every response row includes source: "OECD" per OECD terms of use
• Small results (few countries, narrow time range): every observation is returned inline, in structuredContent and in the rendered table alike — no canvas_id, and truncated is omitted rather than set to false
• Large results (multi-country, multi-year time-series) with CANVAS_PROVIDER_TYPE=duckdb: a leading preview slice plus canvas_id + truncated: true — use oecd_dataframe_describe to list tables, then oecd_dataframe_query for SQL analytics
• Large results without DataCanvas: there is nowhere to stage the remainder, so every observation still comes back in structuredContent, while the rendered table stops at the same preview budget a canvas would have used — the response reports content_table_capped and the number of rows it showed. Narrow the key or the start_period / end_period range to shrink the result itself

oecd_dataframe_describe / oecd_dataframe_query

SQL analytics over observation data staged by oecd_query_dataset.

When oecd_query_dataset returns truncated: true, the full result is staged on a DuckDB-backed DataCanvas. Pass the canvas_id to:

• oecd_dataframe_describe — list staged table names and their columns. Run this first to discover the schema before writing SQL.
• oecd_dataframe_query — run a single-statement SQL SELECT. Supports aggregates, window functions, GROUP BY, ORDER BY, and standard DuckDB SQL.

Requires CANVAS_PROVIDER_TYPE=duckdb. Read-only: writes, DDL, and system catalog access are rejected.

Typical workflow for a large query:

oecd_query_dataset → { canvas_id, table_name, truncated: true, rows: [preview...] }
  → oecd_dataframe_describe(canvas_id) → table/column names
  → oecd_dataframe_query(canvas_id, "SELECT REF_AREA, AVG(value) FROM spilled_... GROUP BY REF_AREA")

Resources

{flow_id} is the combined {dsd_id}@{df_id} string with @ percent-encoded as %40, or the bare {df_id} for a dataflow catalogued without a datastructure prefix. Example: oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I.

All resource data is also reachable via tools. Use oecd_get_dataset_info for the same content.

Features