Server definition
- Hash
- sha256:22fa9b5abb9a891b948bd409190a1b6723d54ec88d7b30381570cf527c933ea0
- What it is
- What a remote MCP server returned when asked what it offers: 7 tools
The blob, as servednamed by its sha256
{
"instructions": "OECD Statistics MCP server — keyless access to 1,500+ OECD dataflows via SDMX 2.1.\nWorkflow: oecd_list_agencies → oecd_search_datasets → oecd_get_dataset_info → oecd_get_dimension_values → oecd_query_dataset.\nLarge results (multi-country time-series) spill to DataCanvas; use oecd_dataframe_describe + oecd_dataframe_query for SQL analytics.\nAll data is attributed to OECD per their terms of use.",
"tools": [
{
"description": "List tables and columns staged on a DataCanvas by a prior oecd_query_dataset spill. Call this before oecd_dataframe_query to discover exact table and column names for SQL. Only available when CANVAS_PROVIDER_TYPE=duckdb is set.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Canvas ID returned by oecd_query_dataset — exactly 10 characters of letters, digits, hyphens, and underscores. Identifies the DataCanvas session holding the staged observation tables.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
}
},
"required": [
"canvas_id"
],
"type": "object"
},
"name": "oecd_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"canvas_id",
"tables",
"table_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "The canvas ID whose tables are listed.",
"type": "string"
},
"error": {
"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`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE is unset. `canvas_not_found`: The canvas_id has expired or was never created. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found"
],
"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"
},
"table_count": {
"description": "Total number of tables and views.",
"type": "number"
},
"tables": {
"description": "Tables and views staged on this canvas.",
"items": {
"additionalProperties": false,
"description": "A canvas table or view with row count and column schema.",
"properties": {
"columns": {
"description": "Columns in the table.",
"items": {
"additionalProperties": false,
"description": "A column in the table with its DuckDB type.",
"properties": {
"name": {
"description": "Column name.",
"type": "string"
},
"type": {
"description": "DuckDB column type — e.g. VARCHAR, DOUBLE, BIGINT.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"kind": {
"description": "Object kind: \"table\" or \"view\".",
"type": "string"
},
"name": {
"description": "Table name — use in SQL FROM clauses.",
"type": "string"
},
"row_count": {
"description": "Number of rows in the table.",
"type": "number"
}
},
"required": [
"name",
"kind",
"row_count",
"columns"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Run a read-only SQL SELECT against OECD observation tables staged on a DataCanvas by oecd_query_dataset. Call oecd_dataframe_describe first to discover exact table and column names, then use this tool for aggregation, filtering, GROUP BY, JOIN, and window functions. Only available when CANVAS_PROVIDER_TYPE=duckdb is set.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "Canvas ID returned by oecd_query_dataset — exactly 10 characters of letters, digits, hyphens, and underscores. Identifies the DataCanvas session holding the observation tables.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"sql": {
"description": "Read-only SELECT statement. Reference tables by the names returned by oecd_dataframe_describe. Only SELECT statements are allowed — DDL, DML, and file-reading functions are rejected.",
"type": "string"
}
},
"required": [
"canvas_id",
"sql"
],
"type": "object"
},
"name": "oecd_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"row_count",
"column_names"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"column_names": {
"description": "Column names in the result, in order.",
"items": {
"type": "string"
},
"type": "array"
},
"error": {
"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`: DataCanvas is not configured — CANVAS_PROVIDER_TYPE is unset. `canvas_not_found`: The canvas_id has expired or was never created. `table_not_found`: The SQL names a table this canvas does not hold — it expired, was dropped, or the name is wrong. `invalid_sql`: The SQL is not a valid SELECT statement or contains disallowed operations. `sql_execution_error`: The SQL parsed and ran, then failed on the staged observation data — a conversion, an invalid input, or a value out of range. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found",
"table_not_found",
"invalid_sql",
"sql_execution_error"
],
"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"
},
"row_count": {
"description": "Full result count before any row cap.",
"type": "number"
},
"rows": {
"description": "Result rows from the SQL query (capped at the canvas row limit).",
"items": {
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Fetch a dataflow's dimensions, their order, and how to construct a query key. Returns per-dimension names, codelist references, and position in the dot-delimited key. Required before calling oecd_query_dataset to understand key structure.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"flow_ref": {
"description": "Full flow reference, either {agencyID},{dsd_id}@{df_id} — e.g. \"OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I\" — or the bare {agencyID},{df_id} form OECD uses for the few dataflows published without a datastructure prefix. Obtain from oecd_search_datasets.",
"type": "string"
}
},
"required": [
"flow_ref"
],
"type": "object"
},
"name": "oecd_get_dataset_info",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"flow_ref",
"dimensions",
"key_example",
"non_production",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dimensions": {
"description": "Dimensions in ascending position order.",
"items": {
"additionalProperties": false,
"description": "A dataflow dimension with its key position and codelist reference.",
"properties": {
"codelist_ref": {
"description": "Codelist reference in the form {agencyID},{codelistID} — use with oecd_get_dimension_values.",
"type": "string"
},
"id": {
"description": "Dimension identifier — e.g. REF_AREA.",
"type": "string"
},
"name": {
"description": "Concept name for the dimension — e.g. \"Reference area\" for REF_AREA. Repeats the id when OECD publishes no concept for it.",
"type": "string"
},
"position": {
"description": "1-based position in the dot-delimited key. Segment at this position corresponds to this dimension.",
"type": "number"
}
},
"required": [
"id",
"name",
"position"
],
"type": "object"
},
"type": "array"
},
"error": {
"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: `invalid_flow_ref`: The flow_ref parameter matches neither the {agencyID},{dsd_id}@{df_id} nor the {agencyID},{df_id} format. `dataflow_not_found`: No datastructure was found for the provided flow_ref. `rate_limited`: OECD throttled the request rate and was still refusing after the retries. `upstream_timeout`: OECD did not finish responding before OECD_TIMEOUT_MS elapsed. `upstream_unavailable`: OECD returned a server fault or was unreachable once the retries ran out. `upstream_redirect`: The configured OECD host answered with a redirect, which this server never follows. `upstream_error`: OECD refused the request with a status this server does not model — an authorization challenge, a rejection from something sitting in front of the API, or a request read as malformed. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_flow_ref",
"dataflow_not_found",
"rate_limited",
"upstream_timeout",
"upstream_unavailable",
"upstream_redirect",
"upstream_error"
],
"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"
},
"flow_ref": {
"description": "The resolved flow reference.",
"type": "string"
},
"key_example": {
"description": "Example dot-delimited key with wildcards — each dot corresponds to one dimension in position order. Empty segments are wildcards. Replace with actual codes from oecd_get_dimension_values.",
"type": "string"
},
"non_production": {
"description": "True if OECD flagged this dataflow as experimental or deprecated.",
"type": "boolean"
},
"source": {
"const": "OECD",
"description": "Data source attribution — always \"OECD\".",
"type": "string"
},
"time_dimension": {
"additionalProperties": false,
"description": "Time dimension — used for startPeriod/endPeriod filtering in oecd_query_dataset.",
"properties": {
"id": {
"description": "Time dimension identifier — typically TIME_PERIOD.",
"type": "string"
},
"name": {
"description": "Concept name for the time dimension, repeating the id when none is published.",
"type": "string"
},
"position": {
"description": "Position after all regular dimensions.",
"type": "number"
}
},
"required": [
"id",
"name",
"position"
],
"type": "object"
}
},
"type": "object"
}
},
{
"description": "Fetch the valid codes and labels for one dimension of a dataflow. Use to resolve human-readable names (countries, measures) to SDMX codes before querying with oecd_query_dataset. Pass query to match a code or label by substring — codelists run to a thousand-plus entries, and the response is a page of at most limit codes either way.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"dimension_id": {
"description": "Dimension identifier to fetch codes for — e.g. \"REF_AREA\" or \"MEASURE\". Obtain valid dimension IDs from oecd_get_dataset_info.",
"type": "string"
},
"flow_ref": {
"description": "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.",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum codes to return (1–500, default 50).",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first code to return within the matching list, applied before limit. Advance it to page; an offset past the last match returns an empty page.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Case-insensitive substring matched against both the code and its label, so \"PA\" and \"percent\" each reach the code \"PA\" / \"Percent per annum\". Omit to page the whole codelist.",
"type": "string"
}
},
"required": [
"flow_ref",
"dimension_id"
],
"type": "object"
},
"name": "oecd_get_dimension_values",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"flow_ref",
"dimension_id",
"codes",
"code_count",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"code_count": {
"description": "Number of codes in this page — not the size of the dimension's codelist.",
"type": "number"
},
"codes": {
"description": "The requested page of codes, after query, offset, and limit are applied.",
"items": {
"additionalProperties": false,
"description": "A valid SDMX code and its human-readable label.",
"properties": {
"id": {
"description": "SDMX code — use in the dimension key for oecd_query_dataset.",
"type": "string"
},
"name": {
"description": "Human-readable label for the code.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"dimension_id": {
"description": "The dimension whose codes are listed.",
"type": "string"
},
"effectiveQuery": {
"description": "The substring filter as applied. Absent when the whole codelist was paged.",
"type": "string"
},
"error": {
"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: `invalid_flow_ref`: The flow_ref parameter matches neither the {agencyID},{dsd_id}@{df_id} nor the {agencyID},{df_id} format. `dataflow_not_found`: The flow_ref does not correspond to a known dataflow. `dimension_not_found`: The dimension_id is not present in this dataflow's structure. `rate_limited`: OECD throttled the request rate and was still refusing after the retries. `upstream_timeout`: OECD did not finish responding before OECD_TIMEOUT_MS elapsed. `upstream_unavailable`: OECD returned a server fault or was unreachable once the retries ran out. `upstream_redirect`: The configured OECD host answered with a redirect, which this server never follows. `upstream_error`: OECD refused the request with a status this server does not model — an authorization challenge, a rejection from something sitting in front of the API, or a request read as malformed. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_flow_ref",
"dataflow_not_found",
"dimension_not_found",
"rate_limited",
"upstream_timeout",
"upstream_unavailable",
"upstream_redirect",
"upstream_error"
],
"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"
},
"flow_ref": {
"description": "The flow reference this dimension belongs to.",
"type": "string"
},
"notice": {
"description": "Present when the page needs explaining — the dimension has no codelist, the query matched nothing, or codes remain beyond the page. States how to reach the rest.",
"type": "string"
},
"source": {
"const": "OECD",
"description": "Data source attribution — always \"OECD\".",
"type": "string"
},
"totalCount": {
"description": "Codes matching before offset and limit, disclosed when the page does not cover them all.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List OECD SDMX agencies, the directorate each belongs to, and the number of dataflows each publishes. Use to discover agency IDs before filtering oecd_search_datasets by department.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "oecd_list_agencies",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"agencies",
"total_agencies",
"total_dataflows",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"agencies": {
"description": "Agencies and their dataflow counts, sorted descending by count.",
"items": {
"additionalProperties": false,
"description": "An agency, its directorate, and its dataflow count.",
"properties": {
"agency_id": {
"description": "Agency identifier — e.g. OECD.SDD.NAD.",
"type": "string"
},
"dataflow_count": {
"description": "Number of dataflows published by this agency.",
"type": "number"
},
"directorate": {
"description": "Name of the OECD directorate the agency sits in, resolved from the directorate segment of the identifier — OECD.SDD.NAD is \"Statistics and Data Directorate\". Absent for a publisher outside OECD and when the agency scheme could not be reached.",
"type": "string"
}
},
"required": [
"agency_id",
"dataflow_count"
],
"type": "object"
},
"type": "array"
},
"error": {
"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: `rate_limited`: OECD throttled the request rate and was still refusing after the retries. `upstream_timeout`: OECD did not finish responding before OECD_TIMEOUT_MS elapsed. `upstream_unavailable`: OECD returned a server fault or was unreachable once the retries ran out. `upstream_redirect`: The configured OECD host answered with a redirect, which this server never follows. `upstream_error`: OECD refused the request with a status this server does not model — an authorization challenge, a rejection from something sitting in front of the API, or a request read as malformed. Other values are possible when a failure originates below the handler.",
"examples": [
"rate_limited",
"upstream_timeout",
"upstream_unavailable",
"upstream_redirect",
"upstream_error"
],
"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"
},
"source": {
"const": "OECD",
"description": "Data source attribution — always \"OECD\".",
"type": "string"
},
"total_agencies": {
"description": "Total number of distinct agencies.",
"type": "number"
},
"total_dataflows": {
"description": "Total number of dataflows across all agencies.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"canvas_id": {
"description": "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.",
"pattern": "^[A-Za-z0-9_-]{10}$",
"type": "string"
},
"end_period": {
"description": "End of the time range — ISO period code such as \"2023\" or \"2023-Q4\". Omit to include up to the latest available period.",
"type": "string"
},
"flow_ref": {
"description": "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.",
"type": "string"
},
"key": {
"description": "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.",
"type": "string"
},
"start_period": {
"description": "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).",
"type": "string"
}
},
"required": [
"flow_ref",
"key"
],
"type": "object"
},
"name": "oecd_query_dataset",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"row_count",
"query_flow_ref",
"query_key",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"canvas_id": {
"description": "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.",
"type": "string"
},
"content_table_capped": {
"description": "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.",
"type": "boolean"
},
"content_table_rows": {
"description": "Rows the rendered table shows when content_table_capped is true.",
"type": "number"
},
"error": {
"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: `invalid_flow_ref`: The flow_ref parameter matches neither the {agencyID},{dsd_id}@{df_id} nor the {agencyID},{df_id} format. `dataflow_not_found`: The flow_ref does not correspond to a known OECD dataflow. `no_results`: The dataflow exists but no observations matched the key and time range. `invalid_key`: OECD rejected the dimension key — wrong number of segments, or an unsupported format. `invalid_period`: OECD could not parse start_period or end_period. `rate_limited`: OECD throttled the request rate and was still refusing after the retries. `download_limit`: OECD refused the query for exceeding its data-download or data-range limit. `upstream_timeout`: OECD did not finish responding before OECD_TIMEOUT_MS elapsed. `upstream_unavailable`: OECD returned a server fault or was unreachable once the retries ran out. `upstream_redirect`: The configured OECD host answered with a redirect, which this server never follows. `upstream_error`: OECD refused the request with a status this server does not model — an authorization challenge, a rejection from something sitting in front of the API, or a request read as malformed. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_flow_ref",
"dataflow_not_found",
"no_results",
"invalid_key",
"invalid_period",
"rate_limited",
"download_limit",
"upstream_timeout",
"upstream_unavailable",
"upstream_redirect",
"upstream_error"
],
"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"
},
"query_end_period": {
"description": "End period filter applied in this query, if any.",
"type": "string"
},
"query_flow_ref": {
"description": "Flow reference used in this query.",
"type": "string"
},
"query_key": {
"description": "Dimension key used in this query.",
"type": "string"
},
"query_start_period": {
"description": "Start period filter applied in this query, if any.",
"type": "string"
},
"row_count": {
"description": "Total rows in the result (or on the canvas when truncated).",
"type": "number"
},
"rows": {
"description": "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.",
"items": {
"additionalProperties": {},
"description": "Decoded observation row. One key per dataflow dimension (e.g. REF_AREA, TIME_PERIOD) and per observation attribute (e.g. UNIT_MULT, OBS_STATUS, PRICE_BASE), each holding a human-readable label; attributes absent from this slice are omitted. Plus \"value\" — the observation already multiplied by \"value_scale\", the power of ten from UNIT_MULT (1 when the dataflow declares no multiplier; divide value by it for the figure as OECD published it) — and \"source\" (\"OECD\").",
"properties": {},
"type": "object"
},
"type": "array"
},
"source": {
"const": "OECD",
"description": "Data source attribution — always \"OECD\".",
"type": "string"
},
"table_name": {
"description": "Canvas table name holding the full result — present when canvas_id is set.",
"type": "string"
},
"truncated": {
"description": "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.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Search OECD dataflows by keyword or theme, matching against dataflow names and descriptions. Returns flow_ref identifiers, names, and agency IDs for use with oecd_get_dataset_info.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_id": {
"description": "Optional agency identifier to restrict the search scope — e.g. \"OECD.SDD.NAD\". Obtain valid agency IDs from oecd_list_agencies.",
"type": "string"
},
"limit": {
"default": 20,
"description": "Maximum number of results to return (1–100, default 20).",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first match to return, applied before limit. Page through results past the limit by advancing it; an offset at or past total_matches returns an empty list.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Keyword or phrase to search for in dataflow names and descriptions — e.g. \"GDP\", \"employment\", \"education\". Every whitespace-separated token must appear somewhere in the name or description.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "oecd_search_datasets",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflows",
"result_count",
"total_matches",
"offset",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dataflows": {
"description": "Matching dataflows for the requested page, up to the requested limit.",
"items": {
"additionalProperties": false,
"description": "A matching OECD dataflow entry.",
"properties": {
"agency_id": {
"description": "Publishing agency identifier.",
"type": "string"
},
"description": {
"description": "Plain-text abstract of what the dataset covers, truncated to 240 characters. Matching runs against the full abstract, so a term reported in matched_in may sit past the cut. Absent when OECD publishes no description for the dataflow.",
"type": "string"
},
"flow_ref": {
"description": "Full flow reference — {agencyID},{dsd_id}@{df_id}, or {agencyID},{df_id} for the few dataflows OECD publishes without a datastructure prefix. Pass through unchanged to oecd_get_dataset_info or oecd_query_dataset.",
"type": "string"
},
"matched_in": {
"description": "Which field carried every query token — \"name\" or \"description\" when only that one did, \"both\" when each did on its own or the tokens were split across the two.",
"enum": [
"name",
"description",
"both"
],
"type": "string"
},
"name": {
"description": "Human-readable dataflow name.",
"type": "string"
},
"non_production": {
"description": "True if flagged as experimental or deprecated by OECD.",
"type": "boolean"
}
},
"required": [
"flow_ref",
"agency_id",
"name",
"matched_in",
"non_production"
],
"type": "object"
},
"type": "array"
},
"error": {
"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: `no_match`: No dataflows matched the search query. `agency_not_found`: The supplied agency_id does not exist in the OECD SDMX catalog. `rate_limited`: OECD throttled the request rate and was still refusing after the retries. `upstream_timeout`: OECD did not finish responding before OECD_TIMEOUT_MS elapsed. `upstream_unavailable`: OECD returned a server fault or was unreachable once the retries ran out. `upstream_redirect`: The configured OECD host answered with a redirect, which this server never follows. `upstream_error`: OECD refused the request with a status this server does not model — an authorization challenge, a rejection from something sitting in front of the API, or a request read as malformed. Other values are possible when a failure originates below the handler.",
"examples": [
"no_match",
"agency_not_found",
"rate_limited",
"upstream_timeout",
"upstream_unavailable",
"upstream_redirect",
"upstream_error"
],
"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"
},
"offset": {
"description": "Zero-based index of the first returned result within the full match list.",
"type": "number"
},
"result_count": {
"description": "Number of results returned (may be less than total_matches).",
"type": "number"
},
"source": {
"const": "OECD",
"description": "Data source attribution — always \"OECD\".",
"type": "string"
},
"totalCount": {
"description": "Total dataflows matching the query, disclosed when matches remain beyond the returned page.",
"type": "number"
},
"total_matches": {
"description": "Total dataflows matching the query before applying offset and limit.",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:22fa9b5abb9a891b948bd409190a1b6723d54ec88d7b30381570cf527c933ea0 | sha256sum