top_n
Fetch the top or bottom N records from an ATO dataset, ranked by a chosen measure, using server-side sorting to save tokens and time.
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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | Curated dataset ID. Use search_datasets() / list_curated(). | |
| measure | Yes | Plain-English measure key to rank by. Use describe_dataset() to see available measures. | |
| n | No | How many top (or bottom) rows to return. | |
| filters | No | Optional dimension filters, same shape as get_data. | |
| direction | No | 'top' returns the N rows with the LARGEST measure values (highest tax payable, biggest population, etc.). 'bottom' returns the SMALLEST. | top |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | ||
| dataset_name | Yes | ||
| query | No | ||
| period | No | ||
| unit | No | ||
| row_count | No | ||
| records | No | ||
| csv | No | ||
| source | No | Australian Taxation Office | |
| 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/ | |
| retrieved_at | Yes | ||
| ato_url | Yes | ||
| server_version | No |