Tools

Six tools covering the full IMF SDMX 3.0 query workflow, plus a DuckDB-backed canvas layer for SQL analytics over large multi-country result sets:

imf_list_databases

Entry point for every IMF query workflow — browse and filter the dataflow catalog, a page at a time.

• Hundreds of dataflows covering WEO projections, balance of payments, CPI, exchange rates, money/finance statistics, and national accounts
• Vintage (historical snapshot) dataflows excluded by default; set include_vintages=true to include them
• Case-insensitive substring filter across ID, name, and description — matched against the full description, not the shortened one returned
• Paged: limit (default 50, max 200) and offset. total_count is the number of matches, returned_count the size of the page, and a notice names the next offset while matches remain
• Descriptions are cut to 200 characters here; imf_get_database and the imf://database/{dataflow_id} resource return the full text for the dataflow you settle on

imf_get_database

Resolve human-readable terms to SDMX dimension codes before querying.

• Returns every dimension ID, its position, its label from the DSD concept scheme (WGT_TYPE → Weight Type), and a codelist preview (e.g. "United States" → USA, "Constant prices" → NGDP_RPCH)
• Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE)
• key_format field shows the exact dot-separated dimension order required by imf_query_dataset
• Every codelist preview is bounded at 50 entries, including substring-filtered previews. Set dimension_id to page one codelist with limit/offset; codelist_filter still applies its case-insensitive substring match before paging
• Set available_only=true to replace codelists with codes reported by the dataflow-wide availability constraint. The response includes total series and time coverage, joins each available code to its DSD label with an ID fallback, and applies dimension_id, codelist_filter, limit, and offset after availability filtering. Omit dimension_id for a bounded preview of every structure dimension, including empty dimensions the constraint does not mention
• A filter that matches nothing is reported distinctly from a codelist that could not be resolved — the two need opposite next steps

imf_query_dataset

Query an IMF SDMX dataflow by dimension key over a time range.

• Dot-separated key in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO annual GDP at constant prices, percent change)
• + combines codes at one position (e.g. USA+GBR+DEU.NGDP_RPCH.A); * matches every code at a position (*.NGDP_RPCH.A for all countries, CAN.*.A for every indicator). Every position needs a code or a * — a blank segment matches nothing upstream and is rejected
• start_period / end_period accept YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD whatever the series frequency, and cover the whole period they name — end_period: 2023 includes 2023-M12 and 2023-Q4
• Returns observations with time_period, value, status, and series attributes (unit, scale, decimals). Period labels come back as upstream emits them — 2023, 2023-S1, 2023-Q1, 2023-M01, 2023-01-05 — and any of them can be passed straight back in as a bound
• A key resolving to several series carries series_metadata, one unit/scale/decimals entry per series_key, because attributes differ between them: in USA.NGDPD+NGDP_RPCH.*, NGDPD is USD at scale 9 while NGDP_RPCH is PT and unscaled. Canvas rows carry their own series' attributes too. A single-series query keeps the flat series_attributes and no list
• unit is the upstream code — PT, USD, XDC, IX, NUM. Every key shape reports the same unit: the portal drops the unit block when a key uses + on the dimension that carries it, and one extra attributes-only request recovers it, so USA.NGDP_RPCH+NGDPD.A and USA.NGDP_RPCH+NGDPD.* both report USD and PT. That key shape is the only one that costs the second request; every other query makes one. A unit: null therefore means the dataflow publishes none, which many do
• Scale 0 is the upstream sentinel for "no multiplier" — formatted output names it rather than printing a bare 0, and structuredContent keeps the raw code
• Large multi-country or long time-range queries automatically spill to DataCanvas; set output_mode: "canvas" to explicitly stage any result, using canvas_id as the destination when supplied
• staged reports whether the complete result is on DataCanvas; truncated reports only whether observations is an incomplete preview. Staged results always return canvas_id, table_name, and describe-before-query guidance in both MCP result channels
• no_data errors include availability context from the upstream constraint endpoint: a dataflow that publishes no series at all is reported as such and points at a different dataflow, since no key would work; otherwise series_count=0 means the code has no coverage and dataflow_availability names codes that do, while series_count>0 means the combination is wrong and available_codes lists what does have data per dimension, stating how many of how many it is showing when a dimension is too long to list in full
• A valid key whose data lies entirely outside the requested range fails as no_data_in_range, reporting the range the series actually spans — the fix is the range, not the key

imf_dataframe_describe / imf_dataframe_query / imf_dataframe_drop

In-conversation SQL analytics over the observation tables that imf_query_dataset stages on a DuckDB-backed canvas.

When imf_query_dataset returns staged: true, the full dataset is registered as a named table on the canvas. The workflow:

1. Call imf_query_dataset — let large results spill automatically or set output_mode: "canvas"; when staged: true, note the canvas_id and table_name
2. Call imf_dataframe_describe with the canvas_id to discover table schema
3. Call imf_dataframe_query with a SELECT statement for aggregations, cross-country comparisons, or time-series analysis
4. When table cleanup is enabled, call imf_dataframe_drop with a name from imf_dataframe_describe to remove only that table or view