imf-mcp-server

List IMF SDMX dataflows available on the portal. Entry point for every query: imf_get_database and imf_query_dataset both require a dataflow id obtained here. Vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE are excluded by default; set include_vintages=true to include them. Results are paged — 50 per call by default, adjustable with limit and offset — and total_count reports how many dataflows matched. Descriptions are shortened here; imf_get_database returns the full text for a single dataflow.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Optional words to filter results by, split on spaces and commas. A dataflow matches when every word appears, case-insensitively, somewhere in its ID, name, or full description. Example: \"exchange rate\" returns ER and related dataflows; \"WEO outlook\" returns WEO and the regional outlooks built on it.",
      "type": "string",
      "minLength": 1
    },
    "include_vintages": {
      "default": false,
      "description": "Include vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE. Default false — vintages are excluded to keep the discovery surface clean.",
      "type": "boolean"
    },
    "limit": {
      "default": 50,
      "description": "Maximum dataflows to return in this call. Default 50, ceiling 200; total_count reports how many matched, so a partial page is always recognizable as one.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 0,
      "description": "Number of matching dataflows to skip before this page. Combine with limit to page through a broad or unfiltered catalog.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dataflows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Dataflow identifier, e.g. WEO, BOP, CPI."
          },
          "agency_id": {
            "type": "string",
            "description": "Agency that publishes this dataflow, e.g. IMF.RES."
          },
          "version": {
            "type": "string",
            "description": "Dataflow version, e.g. 9.0.0."
          },
          "name": {
            "type": "string",
            "description": "Human-readable dataflow name."
          },
          "description": {
            "description": "Short description, cut to 200 characters and ended with … when longer. imf_get_database and the imf://database/{dataflow_id} resource return the full text.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "agency_id",
          "version",
          "name"
        ],
        "additionalProperties": false,
        "description": "A single IMF SDMX dataflow entry."
      },
      "description": "This page of matching dataflows; pass the id to imf_get_database to resolve dimension codelists."
    },
    "total_count": {
      "type": "number",
      "description": "Dataflows matching filter and include_vintages, before limit and offset are applied. Exceeds returned_count when more pages remain."
    },
    "returned_count": {
      "type": "number",
      "description": "Dataflows in this page — the length of dataflows."
    },
    "offset": {
      "type": "number",
      "description": "Number of matching dataflows skipped before this page."
    },
    "notice": {
      "description": "Populated when the filter matches nothing, or when matches remain beyond this page — explains why and names the next offset to request.",
      "type": "string"
    },
    "truncated": {
      "description": "True when matching dataflows remain beyond this page.",
      "type": "boolean"
    },
    "shown": {
      "description": "Dataflows returned in this page.",
      "type": "number"
    },
    "cap": {
      "description": "The limit that bounded this 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: `dataflow_list_unavailable`: The IMF SDMX structure endpoint that backs the dataflow catalog did not return a usable response. Other values are possible when a failure originates below the handler.",
              "examples": [
                "dataflow_list_unavailable"
              ]
            },
            "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",
        "total_count",
        "returned_count",
        "offset"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch a dataflow's dimension list with a codelist preview for each dimension. Resolves human-readable terms to SDMX codes (e.g. "United States" → USA, "Constant prices" → NGDP_RPCH). Required before imf_query_dataset — SDMX keys are opaque without codelist lookups. Each codelist is capped at the first 50 entries by default, including previews filtered by codelist_filter. Set dimension_id to retrieve one codelist with bounded limit/offset paging after the optional codelist_filter, which keeps codes whose ID or name contains every word given. Set available_only=true to page codes the dataflow actually publishes, with series and time coverage metadata; availability filtering happens before codelist_filter and paging. The imf://database/{dataflow_id} resource provides the same bounded discovery summary. Country codes are ISO 3-letter (USA, GBR, DEU), not ISO 2-letter (US, GB, DE). The key_format field shows the exact dimension order required by imf_query_dataset. Note: codelists enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series in this dataflow.

{
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI."
    },
    "agency_id": {
      "description": "Agency ID that publishes this dataflow, e.g. IMF.RES or IMF.STA. Auto-detected from the dataflow list when omitted.",
      "type": "string"
    },
    "version": {
      "description": "Dataflow version, e.g. 9.0.0. Auto-detected from the dataflow list when omitted.",
      "type": "string"
    },
    "codelist_filter": {
      "description": "Optional words to search for in each dimension's codelist, split on spaces and commas. A code matches when every word appears, case-insensitively, in its code ID or name; different words may match different fields. Filtering runs before the 50-entry preview or selected-dimension page. Example: \"CPI\", \"GDP constant prices\", or \"NGDP_RPCH percent\" surfaces matching WEO indicator codes.",
      "type": "string",
      "minLength": 1
    },
    "available_only": {
      "default": false,
      "description": "Return only codes reported by the dataflow-wide availability constraint. Default false keeps ordinary codelist discovery unchanged.",
      "type": "boolean"
    },
    "dimension_id": {
      "description": "Exact dimension ID from this tool, e.g. INDICATOR. Select one dimension to page beyond its preview.",
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "description": "Entries to return from the selected dimension. Valid only with dimension_id; default 50, maximum 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "description": "Matching entries to skip in the selected dimension before this page. Valid only with dimension_id; default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "dataflow_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier, e.g. WEO, BOP, CPI."
    },
    "agency_id": {
      "type": "string",
      "description": "Agency that publishes this dataflow, e.g. IMF.RES, IMF.STA."
    },
    "version": {
      "type": "string",
      "description": "Dataflow version string, e.g. 9.0.0."
    },
    "dsd_version": {
      "description": "Version of the underlying data structure definition (DSD) that backs this dataflow. Differs from version when the dataflow references a shared DSD (e.g. IIP → DSD_BOP at 24.0.0).",
      "type": "string"
    },
    "structure_ref": {
      "description": "Identifier of the underlying DSD, e.g. DSD_BOP. Several dataflows can share one DSD.",
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "Human-readable dataflow name."
    },
    "description": {
      "description": "This dataflow's own description in full — not the shared DSD's, and not the shortened preview imf_list_databases returns for the same id. Absent when the dataflow publishes none.",
      "type": "string"
    },
    "codelist_filter": {
      "description": "Echo of the codelist_filter that produced this result. Absent when no filter was applied — an empty codelist then means the codelist could not be resolved, not that the filter missed.",
      "type": "string"
    },
    "available_only": {
      "description": "True when dimensions contain published availability coverage rather than codelists.",
      "type": "boolean",
      "const": true
    },
    "series_count": {
      "description": "Total series published by the dataflow. Present when available_only is true.",
      "type": "number"
    },
    "time_period_start": {
      "description": "Earliest period with published data, or null when the constraint omits it.",
      "type": [
        "string",
        "null"
      ]
    },
    "time_period_end": {
      "description": "Latest period with published data, or null when the constraint omits it.",
      "type": [
        "string",
        "null"
      ]
    },
    "dimension_id": {
      "description": "Selected dimension ID. Absent when previews for every dimension were returned.",
      "type": "string"
    },
    "key_format": {
      "type": "string",
      "description": "Dimension names in dot-separated keyPosition order, e.g. COUNTRY.INDICATOR.FREQUENCY. Use this exact format when constructing the key for imf_query_dataset."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when any returned dimension page omits matching codes."
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Dimension identifier used in the key, e.g. COUNTRY."
          },
          "name": {
            "type": "string",
            "description": "Human-readable dimension label from the DSD concept scheme, e.g. Weight Type for WGT_TYPE. Falls back to the dimension id when the structure names no concept."
          },
          "position": {
            "type": "number",
            "description": "Zero-based position in the key string."
          },
          "codelist": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Machine code for this dimension value, e.g. USA."
                },
                "name": {
                  "type": "string",
                  "description": "Human-readable label for this value, e.g. United States."
                }
              },
              "required": [
                "id",
                "name"
              ],
              "additionalProperties": false,
              "description": "A single codelist entry: machine code and human-readable name."
            },
            "description": "Valid codelist codes for this dimension, or codes reported with published data when available_only is true. Unselected previews show up to 50 entries after optional filtering. Select dimension_id and use limit/offset for a bounded page of up to 200 entries. Empty means the filter matched nothing when codelist_filter is echoed back, no coverage was reported in availability mode, or the codelist could not be resolved in normal mode — see notice."
          },
          "codelist_truncated": {
            "type": "boolean",
            "description": "True when matching codes were omitted before or after this page."
          },
          "available_count": {
            "description": "Codes reported with published data before codelist_filter. Present when available_only is true.",
            "type": "number"
          },
          "unfiltered_count": {
            "type": "number",
            "description": "Source codes before codelist_filter: the complete resolved codelist normally, or published codes when available_only is true."
          },
          "matched_count": {
            "type": "number",
            "description": "Codes matching codelist_filter before limit and offset are applied."
          },
          "returned_count": {
            "type": "number",
            "description": "Codes returned in this dimension page."
          },
          "offset": {
            "type": "number",
            "description": "Matching codes skipped before this dimension page."
          },
          "next_offset": {
            "description": "Offset for the next page when later matching codes remain.",
            "type": "number"
          }
        },
        "required": [
          "id",
          "name",
          "position",
          "codelist",
          "codelist_truncated",
          "unfiltered_count",
          "matched_count",
          "returned_count",
          "offset"
        ],
        "additionalProperties": false,
        "description": "A single dimension with its codelist or published availability coverage."
      },
      "description": "All dimension previews, or the one selected dimension page."
    },
    "source": {
      "type": "string",
      "description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\"."
    },
    "notice": {
      "description": "Populated when a codelist_filter matched no entries anywhere, or when a dimension has no resolvable codelist, or when offset is past the final match.",
      "type": "string"
    },
    "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: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org. `dimension_not_found`: dimension_id does not match a dimension in the selected dataflow. `structure_unavailable`: api.imf.org returns non-200 on the DSD endpoint. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD lookup is attempted. `availability_unavailable`: available_only is true and the dataflow-wide availability constraint cannot be fetched or parsed. Other values are possible when a failure originates below the handler.",
              "examples": [
                "dataflow_not_found",
                "dimension_not_found",
                "structure_unavailable",
                "dataflow_list_unavailable",
                "availability_unavailable"
              ]
            },
            "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": [
        "dataflow_id",
        "agency_id",
        "version",
        "name",
        "key_format",
        "truncated",
        "dimensions",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Query an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, and status, plus the unit, scale, and decimals of each series — a key resolving to several series carries one entry per series in series_metadata, since unit and scale differ between them. Requires imf_get_database first to obtain the correct key_format and valid dimension codes. Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE). Key format: dot-separated codes in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO). Every position must carry a code: use + to combine codes (e.g. USA+GBR.NGDP_RPCH.A) and * to match every code at a position (e.g. *.NGDP_RPCH.A for all countries); * stands alone and cannot join a + list. Codes are matched case-insensitively and checked against each dimension's codelist before the query — an unknown code is rejected with the nearest valid codes. Codelists from imf_get_database enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series. start_period and end_period must be valid period strings (YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD) with start_period no later than end_period; malformed or reversed ranges are rejected. A bound covers the whole period it names, so end_period 2023 includes 2023-M12 and 2023-Q4. last_n_observations keeps each series' last N observations — 1 is each series' latest value, the cheap way to ask many countries for their latest figure. Values are in base units everywhere, staged canvas rows included: scale is the power of ten the IMF publishes a series in (value / 10^scale is the published figure), never a factor still to apply. A response is held to 100,000 serialized characters. With DataCanvas enabled (CANVAS_PROVIDER_TYPE=duckdb), a larger result (multi-country, long time range) spills to it: call imf_dataframe_describe first to inspect staged tables and columns, then imf_dataframe_query for SQL analysis. Without DataCanvas, a larger result returns its earliest observations with truncated=true, and retrieval_guidance names the last period returned and how to narrow the query.

{
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Matched case-insensitively; the response echoes the catalog spelling."
    },
    "agency_id": {
      "description": "Agency ID, e.g. IMF.RES or IMF.STA. Auto-detected from dataflow list when omitted.",
      "type": "string"
    },
    "version": {
      "description": "Dataflow version. Auto-detected from dataflow list when omitted.",
      "type": "string"
    },
    "key": {
      "type": "string",
      "description": "Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to combine codes at one position (e.g. USA+GBR.NGDP_RPCH.A). Use * to match every code at a position — *.NGDP_RPCH.A returns the indicator for all countries, and CAN.*.A every indicator for Canada. Every position needs a code or a *; an empty segment (USA..A) is rejected. A * stands alone at its position — combined with other codes (USA+*) it is rejected. Codes are trimmed and matched case-insensitively (usa resolves to USA), and the response echoes the canonical key. A code missing from its dimension's codelist is rejected before the query, naming the nearest valid codes. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."
    },
    "start_period": {
      "description": "Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or a calendar-valid YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result.",
      "type": "string"
    },
    "end_period": {
      "description": "End of time range (inclusive). Same formats as start_period, and must not be earlier than it. The bound covers the whole period it names, so end_period 2023 admits 2023-M12 and 2023-Q4. Observations after this period are excluded from the result.",
      "type": "string"
    },
    "last_n_observations": {
      "description": "Keep only each series' last N observations, an integer from 1 to 10,000; 1 returns each series' latest value. Latest is per series: series end at different periods, and a WEO series ends in its projection years (e.g. 2031), so set end_period to stop at a past year. With start_period or end_period, the last N inside that range. A series with fewer than N observations is returned whole. Omit to return every observation.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "canvas_id": {
      "description": "Existing canvas ID to accumulate results into across multiple queries. This selects the destination only; it does not force staging. Use output_mode=\"canvas\" to stage an under-budget result.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    },
    "output_mode": {
      "default": "auto",
      "description": "Result placement. auto returns an under-budget result inline and spills only when needed. canvas explicitly stages the full result, using canvas_id when supplied or allocating a fresh canvas.",
      "type": "string",
      "enum": [
        "auto",
        "canvas"
      ]
    }
  },
  "required": [
    "dataflow_id",
    "key"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier that was queried, in its catalog spelling, e.g. WEO."
    },
    "key": {
      "type": "string",
      "description": "Dimension key used in the query, trimmed and with each code in its codelist spelling, e.g. USA.NGDP_RPCH.A."
    },
    "start_period": {
      "description": "Earliest period covered; absent when the full available range was used.",
      "type": "string"
    },
    "end_period": {
      "description": "Latest period covered; absent when the full available range was used.",
      "type": "string"
    },
    "last_n_observations": {
      "description": "The last_n_observations input, echoed when set: observations holds each series' last N in the range. Absent when every observation was returned.",
      "type": "number"
    },
    "observations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "series_key": {
            "type": "string",
            "description": "Dot-separated dimension codes identifying this series, e.g. USA.NGDP_RPCH.A. Matches the single-country equivalent of the query key — useful when a query covers multiple countries."
          },
          "time_period": {
            "type": "string",
            "description": "Time label as emitted by the upstream API. Annual: YYYY (e.g. 2023). Semi-annual: YYYY-SN (e.g. 2023-S1). Quarterly: YYYY-QN (e.g. 2023-Q1). Monthly: YYYY-MNN (e.g. 2023-M01, not YYYY-MM). Daily: YYYY-MM-DD (e.g. 2023-01-05). Every one of these is also accepted as a start_period/end_period bound, so a label from this field can be passed straight back in."
          },
          "value": {
            "description": "Observation value in base units, e.g. 29298025000000 for US GDP of $29.3 trillion; null when missing. The series' scale is already reflected in it: never apply scale to this value.",
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "description": "Observation status flag exactly as the dataflow publishes it, e.g. T, B, C, or NA; null when the observation carries none. The flags are not a shared vocabulary across dataflows. A null value with no status, or whose only status is the not-available marker NA or n.a. (any letter case), is omitted as padding; a null value with any other status is returned.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "series_key",
          "time_period",
          "value",
          "status"
        ],
        "additionalProperties": false,
        "description": "A single time-series observation."
      },
      "description": "Inline observations, oldest period first. When truncated=true this is the budget-limited time-ascending prefix of the result; observation_count remains the full count."
    },
    "series_attributes": {
      "type": "object",
      "properties": {
        "unit": {
          "description": "Unit of measure as the upstream code, e.g. PT (percent), USD, XDC (domestic currency), NUM (count). Null when the response carries no unit for the series — many dataflows publish none.",
          "type": [
            "string",
            "null"
          ]
        },
        "scale": {
          "description": "Power of ten the IMF publishes this series in, as the upstream code: \"9\" is billions, \"6\" millions, \"0\" units. Observation values are already in base units, so the published figure is value / 10^scale.",
          "type": [
            "string",
            "null"
          ]
        },
        "decimals": {
          "description": "Number of decimal places shown.",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "unit",
        "scale",
        "decimals"
      ],
      "additionalProperties": false,
      "description": "Attributes of the first series in the result — the same series as series_metadata[0]. A key with + or * resolves to several series whose scale and unit differ, and this field describes only the first of them: read series_metadata for the rest, and never apply these values to another series_key."
    },
    "series_metadata": {
      "description": "Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Unit and scale differ across series in one query — WEO NGDPD is USD published in billions (scale 9) while NGDP_RPCH is PT at scale 0 — so interpret each series against its own entry.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "series_key": {
            "type": "string",
            "description": "Series these attributes belong to, matching observations[].series_key."
          },
          "unit": {
            "description": "Unit of measure for this series as the upstream code, e.g. PT (percent), USD, XDC (domestic currency). Null when the response carries none for it.",
            "type": [
              "string",
              "null"
            ]
          },
          "scale": {
            "description": "Power of ten the IMF publishes this series in, as the upstream code: \"9\" is billions, \"0\" units. This series' observation values are already in base units.",
            "type": [
              "string",
              "null"
            ]
          },
          "decimals": {
            "description": "Number of decimal places shown for this series.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "series_key",
          "unit",
          "scale",
          "decimals"
        ],
        "additionalProperties": false,
        "description": "Unit, scale, and decimals for one series in the result."
      }
    },
    "observation_count": {
      "type": "number",
      "description": "Total observations in the result, after any last_n_observations selection."
    },
    "staged": {
      "type": "boolean",
      "description": "True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true."
    },
    "truncated": {
      "type": "boolean",
      "description": "True only when observations is an incomplete preview of observation_count. A result can be staged=true and truncated=false when every observation also fits inline, and staged=false and truncated=true when DataCanvas is not enabled and the full result exceeds the response budget."
    },
    "canvas_id": {
      "description": "DataCanvas session ID — present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query.",
      "type": "string"
    },
    "table_name": {
      "description": "DuckDB table name on the canvas — present when staged=true; reference in SQL via FROM <table_name>.",
      "type": "string"
    },
    "retrieval_guidance": {
      "description": "Present on every staged result, where it names the imf_dataframe_describe-before-imf_dataframe_query retrieval workflow, and on a result truncated without DataCanvas, where it names the last time_period returned and how to narrow the query for the rest.",
      "type": "string"
    },
    "source": {
      "type": "string",
      "description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\"."
    },
    "notice": {
      "description": "Populated when a period bound was set but some observations carry a time_period label the range filter does not recognize. Composes with retrieval_guidance, staged or not, when both apply.",
      "type": "string"
    },
    "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: `dataflow_not_found`: dataflow_id does not match any known dataflow on api.imf.org. `no_data`: Key is structurally valid but the dataflow holds no series for this code combination, or the dataflow publishes no series at all. `no_data_in_range`: The key returned observations but start_period/end_period excluded every one of them. `key_dimension_mismatch`: Number of dot-separated segments in key does not match the dataflow's DSD dimension count. `empty_key_segment`: A dot-separated position in key is empty or blank, which matches no series upstream. `wildcard_in_code_list`: A key position combines * with other codes in a + list, where the portal ignores the * and returns only the listed codes. `invalid_key_code`: A key code is not in its dimension's codelist, checked before any data request. `invalid_period_format`: start_period or end_period is not one of the recognized period formats. `invalid_period_range`: start_period is later than end_period. `structure_unavailable`: The dataflow structure (DSD) cannot be fetched after the dataflow catalog resolved successfully. `canvas_unavailable`: output_mode=\"canvas\" was requested but DataCanvas is disabled. `response_too_large`: The fixed part of the result — full series_metadata, plus the retrieval handle when staging — exceeds the response budget before any observation can be included. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD and data lookups are attempted. Other values are possible when a failure originates below the handler.",
              "examples": [
                "dataflow_not_found",
                "no_data",
                "no_data_in_range",
                "key_dimension_mismatch",
                "empty_key_segment",
                "wildcard_in_code_list",
                "invalid_key_code",
                "invalid_period_format",
                "invalid_period_range",
                "structure_unavailable",
                "canvas_unavailable",
                "response_too_large",
                "dataflow_list_unavailable"
              ]
            },
            "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": [
        "dataflow_id",
        "key",
        "observations",
        "series_attributes",
        "observation_count",
        "staged",
        "truncated",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List DataCanvas tables and columns staged by a prior imf_query_dataset call. Returns each table's name, row count, and column schema (name + DuckDB type). Required before imf_dataframe_query to discover the table and column names for SQL.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by imf_query_dataset whenever staged=true, from automatic spillover or output_mode=\"canvas\"."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "Canvas session ID that was introspected."
    },
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table name — use this in imf_dataframe_query SQL."
          },
          "row_count": {
            "type": "number",
            "description": "Number of rows in this table."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name — use this in SELECT and WHERE clauses."
                },
                "type": {
                  "type": "string",
                  "description": "DuckDB column type, e.g. VARCHAR, DOUBLE, BIGINT."
                }
              },
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "description": "A single column definition."
            },
            "description": "Column schema for this table."
          }
        },
        "required": [
          "name",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A single canvas table with its schema."
      },
      "description": "All tables registered on this canvas."
    },
    "table_count": {
      "type": "number",
      "description": "Total number of tables on the canvas."
    },
    "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_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). Other values are possible when a failure originates below the handler.",
              "examples": [
                "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 a DataCanvas table staged by imf_query_dataset. Supports multi-country comparisons, time-series aggregation, and cross-indicator joins. Requires imf_dataframe_describe first to discover table and column names. One SELECT statement per call; a leading WITH … SELECT (CTE) is accepted. DML and DDL are rejected.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by imf_query_dataset whenever staged=true. Call imf_dataframe_describe with it before writing SQL."
    },
    "sql": {
      "type": "string",
      "description": "Read-only SQL SELECT statement — exactly one statement, starting with SELECT or with a WITH … SELECT common table expression. Reference tables by the names returned by imf_dataframe_describe. Example: SELECT time_period, value FROM spilled_abc123 WHERE time_period >= '2010' ORDER BY time_period."
    }
  },
  "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": "A result row — keys are the selected column names, values match the column DuckDB types (string, number, null)."
      },
      "description": "Largest result-row prefix whose complete structured and formatted response fits the 100,000-character response budget, after the canvas row limit (default 10,000) is applied."
    },
    "row_count": {
      "type": "number",
      "description": "Number of materialized rows returned in rows. Always equals rows.length and never claims a pre-cap total."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when DataCanvas capped the query at its row limit or the server omitted materialized rows to fit the response-size budget. Page the remainder with a stable ORDER BY plus LIMIT/OFFSET, or narrow the query with WHERE or aggregation."
    },
    "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_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). `missing_table`: The canvas exists but sql references a table that is not staged on it — the table expired, was dropped, or the name is wrong. `invalid_sql`: sql is not a single SELECT statement (a leading WITH … SELECT counts as one), or it is SELECT-shaped but fails to prepare — unknown column, unknown function, or a syntax error. `sql_not_permitted`: sql parses as a SELECT but the read-only gate refuses it — it calls an external-data or PRAGMA table function, reads a system catalog, or plans an operator outside the read-only allowlist. `response_too_large`: The first result row cannot fit in the complete structured and formatted response budget. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_not_found",
                "missing_table",
                "invalid_sql",
                "sql_not_permitted",
                "response_too_large"
              ]
            },
            "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",
        "truncated"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}