Find 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

Args: question: Natural language question about statistical data agencies: Optional agency filter (e.g., ["ESTAT", "OECD"]) language: ISO language code (default "en") keywords: Optional keyword overrides for graph search (auto-extracted if omitted) time_range: Optional time filter (e.g., "2020-2024", "since 2015", "last 5 years") geography: 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. user_country: 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. When the question names no geography, it prefers data covering the user's country, whoever publishes it. topic: 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. currency: 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. product: 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. scalar: Set True when the question wants a single value (one observation) rather than a series/table. Defaults precision to "point" unless precision is given. top_n: Number of top candidates to build URLs for (default 5) cross_source: If True, find structurally analogous dataflows in other agencies (>= 50% shared dimension concepts). Adds an extra graph query per candidate. precision: URL breadth — "point" (one observation's series), "series" (default: headline defaults for unfilled dimensions), or "cube" (full constraint enumeration, the historical behaviour). strict_time: 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. labels: 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, and degrades silently to plain CSV elsewhere. Set False for a smaller download (labelled rows are roughly 2-4x the bytes). debug: Append a per-stage telemetry breakdown to the response (only populated when GSDMX2_MCP_TELEMETRY is enabled). Off by default.