top_n
Retrieve top or bottom N records from a dataset ranked by a selected measure, with server-side sorting to avoid downloading full table.
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 corporate taxpayers in 2023-24 top_n("CORP_TRANSPARENCY", "tax_payable", n=10)
# 20 NSW postcodes with the highest median income (2022-23)
top_n("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
filters={"state": "nsw"}, n=20)
# 5 lowest-income postcodes in QLD
top_n("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
filters={"state": "qld"}, 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 describe_dataset() to see available measures. | |
| direction | No | 'top' returns the N rows with the LARGEST measure values (highest tax payable, biggest population, etc.). 'bottom' returns the SMALLEST. | top |
| dataset_id | Yes | Curated dataset ID. Use search_datasets() / list_curated(). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| csv | No | ||
| unit | No | ||
| query | No | ||
| stale | No | ||
| period | No | ||
| source | No | Australian Taxation Office | |
| ato_url | Yes | Click-through URL for this dataset's source page. ato-mcp legacy name — prefer source_url (canonical) for new code. Both fields are populated identically. | |
| records | No | ||
| row_count | No | ||
| dataset_id | Yes | ||
| source_url | Yes | Canonical click-through URL. Same value as ato_url; both populated for backward compat. | |
| attribution | No | Data sourced from the Australian Taxation Office (and, for charity data, the Australian Charities and Not-for-profits Commission) 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 |