au-compliance-kit

PAYG withholding for one pay

payg_withholding

Read-onlyIdempotent

Exact PAYG tax an Australian employer must withhold from one pay (weekly, fortnightly, monthly or quarterly) under ATO Schedule 1 (NAT 1004), with Schedule 8 for study loans and Schedule 9 for seniors, for 2025-26 or 2026-27. Use it in payroll code or when declaration details matter: tax-free threshold, TFN, residency, HELP, Medicare levy exemption or family variation, tax offsets. Returns whole dollars to withhold, take-home for the pay, the tax scale and a breakdown. For a whole-salary summary use take_home_pay; for a bonus or commission use bonus_withholding. Working holiday makers aren't supported and return an error. Read-only and deterministic.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "earnings": "<earnings>",
      "period": "<period>"
    },
    "name": "payg_withholding"
  }
}

Input Schema

Name	Required	Description
`period`	Yes	Pay period.
`payDate`	No	Pay date (YYYY-MM-DD). Picks the financial year's tables; overrides taxYear.
`seniors`	No	Claims the seniors and pensioners tax offset with this status (uses Schedule 9).
`taxYear`	No	Australian financial year (1 July to 30 June) whose withholding tables to use. Default 2026-27.
`earnings`	Yes	Gross earnings for this pay period in AUD, including taxable allowances and overtime, e.g. 3076.92 for a fortnight.
`studyLoan`	No	Has a HELP, VSL, SSL or other study and training support loan. Default false.
`tfnProvided`	No	Employee gave their tax file number. Default true. False applies the no-TFN rate.
`medicareFamily`	No	Medicare levy variation declaration (lower withholding for low-income families).
`annualTaxOffset`	No	Total annual tax offsets claimed on the withholding declaration (AUD).
`foreignResident`	No	Foreign resident for tax purposes. Default false.
`taxFreeThreshold`	No	Tax-free threshold claimed with this employer. Default true (main job). Use false for a second job.
`medicareExemption`	No	Medicare levy exemption claimed. Default none.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 13, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description adds that the result is deterministic, cites the statutory tables used, describes what the response contains (whole dollars, take-home, tax scale, breakdown), and discloses the error case for unsupported visa categories. That is substantive behavior disclosure rather than restatement of the hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then use cases, outputs, alternatives, and exclusions — zero filler and every sentence carries distinct information. It is dense to the point of being a single wall of clauses, which slightly hurts scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter tool with a nested object and no output schema, the description covers purpose, inputs rationale, return contents, determinism, and the one unsupported case. Nothing an agent needs in order to decide whether and how to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the parameter documentation burden is already met and a baseline of 3 applies. The description adds framing value by grouping the declaration dimensions (tax-free threshold, TFN, residency, HELP, Medicare levy exemption, family variation, offsets) into a single coherent call rationale, though it adds no format or value details the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource — exact PAYG tax an Australian employer must withhold from a single pay — and pins the scope with the governing rules (ATO Schedule 1 NAT 1004, Schedules 8 and 9) and supported years. It distinguishes itself from siblings by pointing to take_home_pay for whole-salary summaries and bonus_withholding for bonuses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames when to reach for it ('in payroll code or when declaration details matter') and names the two alternatives that cover adjacent jobs. It also states a hard exclusion — working holiday makers return an error — so the agent knows the boundary rather than discovering it at call time.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All au-compliance-kit tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.