Aard

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

Browse the full available code list of ONE dimension, one level or page at a time.

Use this when inspect shows a dimension with more codes than it can display (large geographies, detailed product/COICOP classifications). Hierarchical codelists are surfaced one level at a time — top-level codes first, then drill into a code's narrower members with expand. Flat codelists are paginated with offset.

Common workflow: discover -> inspect -> browse_dimension_codes -> build_url

Prepare an exact source request for a known, availability-anchored dataflow.

Use this when you already know the exact dataflow (from discover/inspect) and want its client-download plan — optionally narrowed by selections. Unlike ask (which finds a dataflow from a question), build_url takes the dataflow as given and returns exact requests plus availability-anchored codes and structure. Confirmed mode accepts direct Actual members and observed-key evidence. Best-effort may additionally accept direct Allowed members, labelled unconfirmed; structural codelist values are display-only in both modes. Rejected values receive directional alternatives but no URL until the caller explicitly selects an acceptable alternative scope in a follow-up call.

Does NOT fetch observations. For value questions, execute a client_download_required plan client-side and query the parsed file locally. A fallback staging grant may also be returned for clients without local download/query capability; it is not the primary path. Only a successfully parsed dataset with zero rows, or a verification status of no_records, supports a no-data claim.

Safety: execute the 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.

Common workflow: discover -> inspect -> build_url -> direct download -> local query

Find what official data is available about a topic.

Use this to explore what datasets exist. It returns catalogue metadata, never observations — and neither do ask and build_url, which prepare an exact source request that still has to be downloaded and queried (fetch / stage_url when the client cannot do that itself).

Two response shapes, and shape says which one arrived.

• ranked — results lists matching datasets, best first, each with its dimensions, coverage, and the matches that justify it.

• anchored — topic named one concrete code (a place, a country, an indicator) and nothing forced the ranked path. The answer is then anchor (the code chosen, and what else the topic could have meant), facets (what varies across the datasets publishing it) and anchored_datasets (those datasets, paged by page.next_offset). results is [] on this shape by construction — that is not "nothing found". If the chosen code is wrong, re-query with one of anchor.alternatives[].name.

The two shapes never both appear. Anything that scopes the search is served by the ranked path: agencies, region, user_country, keywords, a non-English language, or an offset past the anchored page. A code also stays ranked when fewer than max(15, limit) datasets publish it (it or a code beneath it), and when resolving it or counting its datasets fails or does not finish in time — that last case, and only it, carries a retrieval_degraded warning with level anchor_unavailable; a retry may then anchor.

Anchored rows are datasets that publish the code or one beneath it — never ones merely permitted to carry it, never ones carrying only its parent.

Two keys explain the rest of the response: _k expands the abbreviated row keys, and _notes explains whatever this particular response happens to contain, keyed by field or field=value.

Common workflow: discover -> inspect -> ask

Return bounded rows for a dataflow — the completion path for hosted clients.

Use this when the client cannot execute a client-download plan locally (no shell/filesystem — e.g. a hosted store app or connector) but still needs actual values. fetch server-side downloads the exact GET/fan-out plan build_url would produce, concatenates it, runs one bounded literal-equality query, and releases the artifact — the raw dataset never enters model context. Clients that CAN execute locally should keep using ask/build_url and run the plan themselves; fetch is the affinity-free hosted shortcut, not the power path.

POST-only selections have no hosted download path: fetch raises fetch_shape_unsupported and the caller must execute the build_url plan client-side. A rejected/over-length selection raises the same reason build_url would report; narrow the selection and retry.

fetch does not page, deliberately. It holds no dataset between calls: every call rebuilds the plan, re-downloads every part from the provider, and releases the artifact. An offset over that would be unsound as well as wasteful — there is no snapshot behind the cursor, so rows shifting upstream between calls would silently skip or duplicate observations, and N pages would mean N full downloads of the same dataflow from an agency that may rate-limit. When a result is truncated, narrow it (select, where, time_range) or switch to stage_url + query_dataset, which pages with offset over ONE immutable staged artifact and downloads once.

Rows are ordered by series key, then period, before limit applies. A series with a period that cannot be placed unambiguously keeps the provider's order.

no_records_for_selection is TERMINAL, not a fault: the request was well-formed and the source holds no observations for it. Widen the selection or state that no data exists — do not retry the same selection. Only upstream_origin_error (an origin fault) and upstream_rate_limited are worth retrying.

Inspect a dataflow's dimensional structure and constraint codes.

Call as: inspect(agency_id="ABS", dataflow_id="ERP_Q")

Returns a brief summary for the user plus full dimensional detail (dimensions, code counts, sample code values with names, constraint type) for the assistant to reason over. Use this to drill into a dataflow found via discover before building a query with ask.

Return cached columns/types and row count, never observation rows.

Return only bounded selected rows using literal equality filters.

There is no SQL, shell, filesystem, network-function, extension, or mutation surface. A safe default limit applies when limit is omitted.

Page with offset: rows come back in the dataset's stored order, and next_offset in the response is the absolute offset to pass as the next call's offset. Stored order is the provider's order, not necessarily chronological; filter TIME_PERIOD with where or sort client-side.

next_offset is null when there is no next page to ask for, which is not the same as having received everything. Check truncated too: null with truncated: false means the matches are exhausted; null with truncated: true means rows remain that this byte budget cannot reach, and min_bytes_required says what budget would.

Idempotently remove a caller-owned staged dataset before its TTL.

Fallback for clients that cannot download and query the source locally.

Use only when local execution is unavailable or the user explicitly asks for Aard-managed staging. Never fetch the URL with web search or request its response body directly. Stage the exact unchanged fallback URL outside model context; this tool returns metadata only. Use its dataset_id with inspect_dataset or query_dataset.

The URL alone is sufficient. download_ref is an optional fast path — if you cannot copy it exactly, OMIT it rather than risk mistyping it; the server then re-derives the grant itself and the call still succeeds.

no_records_for_selection is TERMINAL, not a fault: the request was well-formed and the source holds no observations for it. Widen the selection or state that no data exists — do not retry the same selection.