Fuzzy-search the curated AIHW dataset catalog.

All datasets ship hand-curated in v0.1: long-term mortality (GRIM), regional mortality (MORT), cancer incidence and mortality, health expenditure, youth justice detention, and the public hospitals register.

Examples: # Find a dataset that gives deaths by cause results = await search_datasets("mortality cause of death") # → [{id: 'GRIM_DEATHS', name: 'GRIM — long-term mortality', ...}]

# Discover what's available on cancer
results = await search_datasets("cancer")

Returns: List of DatasetSummary (id, name, description, update_frequency, is_curated), ranked by relevance.

Describe a dataset's filterable dimensions, returnable measures, units, and source.

Use this before calling get_data on a new dataset — it tells you the valid filter keys ('sex', 'year', 'state'), the valid filter values ('Females', 'Males', 'Persons'), the measure aliases ('deaths', 'crude_rate_per_100000'), and the canonical source URL.

Returns: DatasetDetail with id, name, description, period_coverage, list of dimensions, list of measures (each with key, source_column, unit, description), and source_url + download_url.

Query a curated AIHW dataset and return observations.

Examples: # Deaths from diabetes, all years and sexes resp = await get_data( "GRIM_DEATHS", filters={"cause_of_death": "Diabetes"}, measures="deaths", )

# Breast cancer incidence in females over time
resp = await get_data(
    "CANCER_INCIDENCE_MORTALITY",
    filters={"cancer_type": "Breast cancer", "sex": "Female", "type": "Incidence"},
)

# Public hospitals in NSW with peer group "Principal referral"
resp = await get_data(
    "PUBLIC_HOSPITALS",
    filters={"state": "NSW", "peer_group_name": "Principal referral"},
)

Returns: DataResponse with records (or csv), unit, period bounds, row_count, source URL, and CC-BY attribution.

Return the most recent observation(s) per measure for a dataset.

For transposed time-series tables this trims to the most-recent period. For wide single-year tables (most AIHW datasets) it returns the same shape as get_data — there is only one period in those tables.

When the curated YAML declares a headline_slice, those filter values are applied automatically so the no-filter call returns ONE canonical headline row (e.g. HEALTH_EXPENDITURE → national total, all areas, all sources). User-supplied filters override the headline_slice per-key — latest("HEALTH_EXPENDITURE", filters={"state": "NSW"}) keeps the area/source defaults and returns the NSW latest-year total.

Examples: # Latest year of GRIM data for All causes combined resp = await latest("GRIM_DEATHS", filters={"cause_of_death": "All causes combined"})

Return the N rows with the largest (or smallest) value of a measure.

This is the most common agent workflow: "show me the top 10 X by Y". Without this tool, an agent would call get_data, receive the full table, and then sort/slice locally — wasting tokens and turns. top_n does the rank server-side and returns only the requested rows.

Examples: # Top 10 causes of death in 2023 (Persons) top_n("GRIM_DEATHS", "deaths", n=10, filters={"sex": "Persons", "year": "2023"})

# 20 SA3 regions with the highest age-standardised mortality
top_n("MORT_GEOGRAPHY", "age_standardised_rate_per_100000",
      filters={"category": "Statistical Area Level 3 (SA3)",
               "sex": "Persons", "year": "2023"}, n=20)

# 5 lowest-funded health expenditure areas in NSW
top_n("HEALTH_EXPENDITURE", "real_expenditure_millions",
      filters={"state": "NSW", "financial_year": "2022-23"},
      n=5, direction="bottom")

Returns: DataResponse with at most n records, sorted by measure value in the requested direction. Other fields (period, unit, attribution) match a regular get_data call.

List every curated dataset ID in this version of aihw-mcp.

These are the datasets where get_data accepts plain-English filter keys and returns aliased, well-typed measure columns. Each ID is documented via describe_dataset.

Returns: Sorted list of dataset IDs.