oecd-mcp-server

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.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "agencies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "agency_id": {
            "type": "string",
            "description": "Agency identifier — e.g. OECD.SDD.NAD."
          },
          "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"
          },
          "dataflow_count": {
            "type": "number",
            "description": "Number of dataflows published by this agency."
          }
        },
        "required": [
          "agency_id",
          "dataflow_count"
        ],
        "additionalProperties": false,
        "description": "An agency, its directorate, and its dataflow count."
      },
      "description": "Agencies and their dataflow counts, sorted descending by count."
    },
    "total_agencies": {
      "type": "number",
      "description": "Total number of distinct agencies."
    },
    "total_dataflows": {
      "type": "number",
      "description": "Total number of dataflows across all agencies."
    },
    "source": {
      "type": "string",
      "const": "OECD",
      "description": "Data source attribution — always \"OECD\"."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "agencies",
        "total_agencies",
        "total_dataflows",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "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."
    },
    "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).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dataflows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "flow_ref": {
            "type": "string",
            "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."
          },
          "agency_id": {
            "type": "string",
            "description": "Publishing agency identifier."
          },
          "name": {
            "type": "string",
            "description": "Human-readable dataflow name."
          },
          "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"
          },
          "matched_in": {
            "type": "string",
            "enum": [
              "name",
              "description",
              "both"
            ],
            "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."
          },
          "non_production": {
            "type": "boolean",
            "description": "True if flagged as experimental or deprecated by OECD."
          }
        },
        "required": [
          "flow_ref",
          "agency_id",
          "name",
          "matched_in",
          "non_production"
        ],
        "additionalProperties": false,
        "description": "A matching OECD dataflow entry."
      },
      "description": "Matching dataflows for the requested page, up to the requested limit."
    },
    "result_count": {
      "type": "number",
      "description": "Number of results returned (may be less than total_matches)."
    },
    "total_matches": {
      "type": "number",
      "description": "Total dataflows matching the query before applying offset and limit."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based index of the first returned result within the full match list."
    },
    "source": {
      "type": "string",
      "const": "OECD",
      "description": "Data source attribution — always \"OECD\"."
    },
    "totalCount": {
      "description": "Total dataflows matching the query, disclosed when matches remain beyond the returned page.",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$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"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "flow_ref": {
      "type": "string",
      "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."
    }
  },
  "required": [
    "flow_ref"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "flow_ref": {
      "type": "string",
      "description": "The resolved flow reference."
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Dimension identifier — e.g. REF_AREA."
          },
          "name": {
            "type": "string",
            "description": "Concept name for the dimension — e.g. \"Reference area\" for REF_AREA. Repeats the id when OECD publishes no concept for it."
          },
          "position": {
            "type": "number",
            "description": "1-based position in the dot-delimited key. Segment at this position corresponds to this dimension."
          },
          "codelist_ref": {
            "description": "Codelist reference in the form {agencyID},{codelistID} — use with oecd_get_dimension_values.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "position"
        ],
        "additionalProperties": false,
        "description": "A dataflow dimension with its key position and codelist reference."
      },
      "description": "Dimensions in ascending position order."
    },
    "time_dimension": {
      "description": "Time dimension — used for startPeriod/endPeriod filtering in oecd_query_dataset.",
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Time dimension identifier — typically TIME_PERIOD."
        },
        "name": {
          "type": "string",
          "description": "Concept name for the time dimension, repeating the id when none is published."
        },
        "position": {
          "type": "number",
          "description": "Position after all regular dimensions."
        }
      },
      "required": [
        "id",
        "name",
        "position"
      ],
      "additionalProperties": false
    },
    "key_example": {
      "type": "string",
      "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."
    },
    "non_production": {
      "type": "boolean",
      "description": "True if OECD flagged this dataflow as experimental or deprecated."
    },
    "source": {
      "type": "string",
      "const": "OECD",
      "description": "Data source attribution — always \"OECD\"."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$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"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "flow_ref": {
      "type": "string",
      "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."
    },
    "dimension_id": {
      "type": "string",
      "description": "Dimension identifier to fetch codes for — e.g. \"REF_AREA\" or \"MEASURE\". Obtain valid dimension IDs from oecd_get_dataset_info."
    },
    "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"
    },
    "limit": {
      "default": 50,
      "description": "Maximum codes to return (1–500, default 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "flow_ref",
    "dimension_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "flow_ref": {
      "type": "string",
      "description": "The flow reference this dimension belongs to."
    },
    "dimension_id": {
      "type": "string",
      "description": "The dimension whose codes are listed."
    },
    "codes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "SDMX code — use in the dimension key for oecd_query_dataset."
          },
          "name": {
            "type": "string",
            "description": "Human-readable label for the code."
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false,
        "description": "A valid SDMX code and its human-readable label."
      },
      "description": "The requested page of codes, after query, offset, and limit are applied."
    },
    "code_count": {
      "type": "number",
      "description": "Number of codes in this page — not the size of the dimension's codelist."
    },
    "source": {
      "type": "string",
      "const": "OECD",
      "description": "Data source attribution — always \"OECD\"."
    },
    "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"
    },
    "effectiveQuery": {
      "description": "The substring filter as applied. Absent when the whole codelist was paged.",
      "type": "string"
    },
    "totalCount": {
      "description": "Codes matching before offset and limit, disclosed when the page does not cover them all.",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$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"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "flow_ref": {
      "type": "string",
      "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."
    },
    "key": {
      "type": "string",
      "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."
    },
    "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"
    },
    "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"
    },
    "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.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "flow_ref",
    "key"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "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\")."
      },
      "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."
    },
    "row_count": {
      "type": "number",
      "description": "Total rows in the result (or on the canvas when truncated)."
    },
    "query_flow_ref": {
      "type": "string",
      "description": "Flow reference used in this query."
    },
    "query_key": {
      "type": "string",
      "description": "Dimension key used in this query."
    },
    "query_start_period": {
      "description": "Start period filter applied in this query, if any.",
      "type": "string"
    },
    "query_end_period": {
      "description": "End period filter applied in this query, if any.",
      "type": "string"
    },
    "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"
    },
    "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"
    },
    "source": {
      "type": "string",
      "const": "OECD",
      "description": "Data source attribution — always \"OECD\"."
    },
    "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": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$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"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "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."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "The canvas ID whose tables are listed."
    },
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table name — use in SQL FROM clauses."
          },
          "kind": {
            "type": "string",
            "description": "Object kind: \"table\" or \"view\"."
          },
          "row_count": {
            "type": "number",
            "description": "Number of rows in the table."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "DuckDB column type — e.g. VARCHAR, DOUBLE, BIGINT."
                }
              },
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "description": "A column in the table with its DuckDB type."
            },
            "description": "Columns in the table."
          }
        },
        "required": [
          "name",
          "kind",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A canvas table or view with row count and column schema."
      },
      "description": "Tables and views staged on this canvas."
    },
    "table_count": {
      "type": "number",
      "description": "Total number of tables and views."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "canvas_id",
        "tables",
        "table_count"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "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."
    },
    "sql": {
      "type": "string",
      "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."
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Result rows from the SQL query (capped at the canvas row limit)."
    },
    "row_count": {
      "type": "number",
      "description": "Full result count before any row cap."
    },
    "column_names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Column names in the result, in order."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rows",
        "row_count",
        "column_names"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}