Fuzzy-search the curated ATO/ACNC dataset catalog.

All datasets ship hand-curated in v0.1: personal tax by postcode, company tax by industry, corporate tax transparency, GST collections, super contributions by age, the ACNC charity register, and more.

Examples: # Find the dataset that gives tax stats by postcode results = await search_datasets("postcode tax") # → [{id: 'IND_POSTCODE', name: 'Individuals by Postcode', ...}]

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

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 ('state', 'postcode', 'industry'), the valid filter values ('nsw', 'vic'), the measure aliases ('median_taxable_income'), 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 ATO/ACNC dataset and return observations.

Examples: # Median taxable income in postcode 2000 (Sydney CBD), 2022-23 resp = await get_data( "IND_POSTCODE_MEDIAN", filters={"state": "nsw", "postcode": "2000"}, measures="median_taxable_income_2022_23", )

# All registered charities in NSW with size = "large"
resp = await get_data(
    "ACNC_REGISTER",
    filters={"state": "NSW", "charity_size": "Large"},
    measures=["total_gross_income", "total_employees"],
)

# 500 ACNC charity financial records (huge dataset — cap to fit context)
resp = await get_data(
    "ACNC_AIS_FINANCIALS",
    filters={"state": "NSW"},
    limit=500,
)

# 2023-24 corporate tax payable for entities with total income > $1B
resp = await get_data("CORP_TRANSPARENCY", filters={"income_year": "2023-24"})

Returns: DataResponse with records (or csv), unit, period bounds, row_count, source URL, and CC-BY attribution. truncated_at is set when the underlying slice was larger than limit.

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

For transposed time-series tables (GST_MONTHLY etc.) this trims to the most-recent period. For wide register-shaped tables (ACNC_REGISTER, IND_POSTCODE etc.) it returns the same shape as get_data, capped at limit rows. Truncated responses set DataResponse.truncated_at.

Examples: # Latest monthly net GST nationally resp = await latest("GST_MONTHLY", measures="net_gst")

# 50 charities (default cap) — narrow with filters to get specific ones
resp = await latest("ACNC_REGISTER", filters={"state": "nsw", "charity_size": "Large"})

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.

Aggregate statistics (count, sum, mean, median, min, max, stddev) for one measure across all rows matching filters. Optionally grouped.

Without group_by: returns one stats payload over all matching rows. With group_by: returns per-group stats — much more powerful for "distribution X by Y" queries that would otherwise require N filtered calls.

Examples: # Single aggregate over NSW postcodes stats("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23", filters={"state": "nsw"}) # → {statistics: {count: 587, mean: 55017, median: 53484, ...}}

# Stats grouped by state — one call instead of 8
stats("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
      group_by="state")
# → {by: "state", groups: [
#     {key: "ACT", statistics: {...}},
#     {key: "NSW", statistics: {...}},
#     ...
# ]}

# Tax payable per income year across the corporate sector
stats("CORP_TRANSPARENCY", "tax_payable", group_by="income_year")

Returns: Without group_by: dict with statistics field. With group_by: dict with by and groups fields; each group carries key, statistics, plus the same envelope metadata (dataset_id, unit, attribution, etc.).

List every curated dataset ID in this version of ato-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.