ato-mcp

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"})

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.

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.

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.).

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.