top_n
Return the highest or lowest N rows from an AIHW dataset ranked by a chosen measure, with optional filters to narrow the results.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | How many top (or bottom) rows to return. | |
| filters | No | Optional dimension filters, same shape as get_data. | |
| measure | Yes | Plain-English measure key to rank by. Use the describe endpoint or describe tool to see available measures. | |
| direction | No | 'top' returns the N rows with the LARGEST measure values (highest deaths, biggest expenditure, etc.). 'bottom' returns the SMALLEST. | top |
| dataset_id | Yes | Curated dataset ID. Use the search or list-curated endpoint/tool to discover. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| csv | No | ||
| unit | No | ||
| query | No | ||
| stale | No | ||
| period | No | ||
| source | No | Australian Institute of Health and Welfare | |
| records | No | ||
| aihw_url | Yes | Click-through URL for this dataset's source page. aihw-mcp legacy name — prefer source_url (canonical) for new code. Both fields are populated identically. | |
| row_count | No | ||
| dataset_id | Yes | ||
| source_url | Yes | Canonical click-through URL. Same value as aihw_url; both populated for backward compat. | |
| attribution | No | Data sourced from the Australian Institute of Health and Welfare (AIHW) via data.gov.au. Licensed under Creative Commons Attribution 3.0 Australia (CC BY 3.0 AU). https://creativecommons.org/licenses/by/3.0/au/ | |
| dataset_name | Yes | ||
| retrieved_at | Yes | ||
| stale_reason | No | ||
| truncated_at | No | ||
| server_version | No |