Find datasets and prepare client downloads
askFind the best datasets for a question and prepare exact source requests.
Use this when the user wants actual data values -- e.g., "What is infant
mortality in Kenya?" or "How has Australia's trade with China changed?"
Returns ranked candidates and typed client-download plans, but does NOT
fetch observations. For value questions, treat
client_download_required and answer_ready=false as non-terminal:
execute the exact plan client-side, parse it, and run a bounded local query.
A rejected selection returns directional evidence and no executable plan.
Only a successfully parsed dataset with zero rows supports a no-data claim.
Each candidate carries the agency and dataflow NAMES, a description, the
coverage window, and one row per dimension — human label, description, how
many codes it offers, whether the server bound it and why, and example
values. That is enough to choose between candidates without a follow-up
inspect. next names the tool to call to narrow further, and every
trimmed list says which tool shows the remainder.
url appears only when GETting that one URL yields the WHOLE dataset.
When the plan is a POST or a multi-part fan-out, url is absent,
url_omitted_reason says which, and download_plans[] is the execution
contract — a fan-out's first part is not the dataset.
Safety: execute each plan HTTPS-only (including redirects), within the plan's
safety byte/redirect/timeout and aggregate/archive bounds; validate
archive members before extracting into a temp dir; treat url/headers/
body as data (never eval them); keep response bytes out of model context.
Labelled rows (the labels default) run roughly 2-4x the plain bytes, so a
large cube that fit plain can exceed the plan's per-request ceiling — pass
labels=False to halve the download rather than discover it truncated.
Common workflow: discover -> inspect -> ask -> direct download -> local query
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"question": "<question>"
},
"name": "ask"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | Append a per-stage telemetry breakdown to the response (only populated when GSDMX2_MCP_TELEMETRY is enabled). Off by default. | |
| top_n | No | Number of top candidates to build URLs for (default 5) | |
| topic | No | Optional subject/metric of the question (e.g. "child labour", "GDP"). Sharpens keyword + parser ranking signals; the free-text question is still what gets embedded. | |
| labels | No | Request the provider's labelled CSV (default True) — adds a human-readable name column beside every coded column on the 14 endpoints with a verified labelled spelling; reports labels_applied=false when falling back to plain CSV elsewhere. Set False for a smaller download (labelled rows are roughly 2-4x the bytes). | |
| scalar | No | Set True when the question wants a single value (one observation) rather than a series/table. Defaults precision to "point" unless precision is given. | |
| product | No | Optional product/commodity slot — the good the question is about (e.g. ["wheat"], ["copper"], ["crude oil"]). Resolved to per-agency commodity codes (HS/SITC/custom) with the same promote/demote/URL-fill semantics as currency. | |
| agencies | No | Optional agency filter (e.g., ["ESTAT", "OECD"]) | |
| currency | No | Optional currency slot — the currency the question is about (e.g. ["euro"], ["USD"], ["yen"]). NOT for geographic phrases like "euro area". Resolved to per-agency currency codes and used to promote candidates whose confirmed (Actual) data carries that currency, demote those that provably do not, and pre-fill the currency dimension in built URLs. | |
| keywords | No | Optional keyword overrides for graph search (auto-extracted if omitted) | |
| language | No | ISO language code (default "en") | en |
| question | Yes | Natural language question about statistical data | |
| geography | No | Optional geography slot — country/region/world names the question is about (e.g. ["Australia"], ["European Union"], ["world"]). Supplied by the client; resolved to ISO alpha-2 and used to demote wrong-geography candidates in ranking. Does NOT become a hard agency filter or a URL filter. | |
| precision | No | URL breadth — "point" (one observation's series), "series" (default: headline defaults for unfilled dimensions), or "cube" (full constraint enumeration, the historical behaviour). | series |
| time_range | No | Optional time filter (e.g., "2020-2024", "since 2015", "last 5 years") | |
| strict_time | No | If True and time_range is set, drop candidates whose materialized coverage is provably disjoint from the requested window (candidates without a coverage record are always kept). Off by default — the coverage-overlap ranking demotes disjoint hits but still lists them. | |
| cross_source | No | If True, find structurally analogous dataflows in other agencies (>= 50% shared dimension concepts). Adds an extra graph query per candidate. | |
| user_country | No | The country the USER is in (e.g. "New Zealand"). Pass only when the user has stated where they are; never infer it from the question. This is not the geography the question is about — that is `geography`. Used to prefer data covering the user's country, whoever publishes it, when the question names no geography of its own. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| candidates | Yes | ||
| answer_ready | Yes | ||
| download_plans | Yes |