Skip to main content
Glama

Calculate.co.nz NZ Calculators

nz_bonus_tax_calculator

Work out the tax on a New Zealand bonus or commission, and what is left.

Use for: 'how much tax will I pay on my bonus', 'why was my bonus taxed so
much', 'what will I actually get from a $10,000 bonus', 'is commission taxed
differently'.

A bonus is an extra emolument. It is NOT taxed at a flat rate and NOT at the
person's ordinary rate. The tax is the difference between tax on
(salary + bonus) and tax on salary alone.

This is why a bonus so often looks over-taxed and is not: when it straddles
a bracket, part is taxed at the lower rate and part at the higher one, so
the effective rate sits between them and above the rate on their salary.
crosses_bracket tells you when to explain this.

ALWAYS ask for the annual salary. The same bonus costs different amounts of
tax depending on the salary underneath it, so an answer without it is a
guess.

Args:
    bonus_amount: Gross bonus or commission in NZD.
    annual_salary: Regular annual salary, excluding the bonus.
    kiwisaver_rate: A DECIMAL, 0.03 for 3%.
    has_student_loan: Whether repayments are deducted.

Returns:
    Income tax on the bonus, its effective rate, ACC, KiwiSaver, student
    loan, and the net amount. ACC stops at the earnings cap and student loan
    only bites above the repayment threshold, both of which are handled.

An employer may deduct at a flat rate through the year and let IRD square it
up at assessment, so a payslip can differ from this and both be correct.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bonus_amountYes
annual_salaryYes
kiwisaver_rateNo
has_student_loanNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and delivers: the calculation rule (tax on salary+bonus minus tax on salary alone), the explanation for why bonuses look overtaxed, the crosses_bracket output signal, ACC cap and student loan threshold handling, and the caveat that employer flat-rate deductions make payslips differ legitimately. It pre-empts the exact behavioral surprises a user will encounter.

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

Conciseness5/5

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

Long but every paragraph earns its place: purpose, usage, mechanics, misconception, required input, args, returns, and a discrepancy caveat. The purpose is front-loaded in sentence one, and the entire description reads in a single logical flow with zero repetition.

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 calculator with no output schema and no annotations, the description discloses inputs, computed outputs (income tax, effective rate, ACC, KiwiSaver, student loan, net), boundary conditions (ACC cap, student loan threshold), and crosses_bracket as a return signal. An agent has everything necessary to invoke it correctly and set user expectations.

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

Parameters5/5

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

Schema description coverage is 0%, and the description compensates fully in the Args block: units for bonus_amount ('Gross... in NZD'), the exclusion for annual_salary ('excluding the bonus'), a format warning for kiwisaver_rate ('A DECIMAL, 0.03 for 3%') that prevents a common 3-vs-0.03 error, and the semantics of has_student_loan.

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 specific verb and resource: 'Work out the tax on a New Zealand bonus or commission, and what is left.' The four example queries pin the intent ('is commission taxed differently') and the bracket-straddling explanation distinguishes it from ordinary PAYE tools. An agent can tell exactly which user request this satisfies.

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

Usage Guidelines4/5

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

Provides an explicit 'Use for' block with concrete query phrasing and a hard requirement ('ALWAYS ask for the annual salary'). However, it never names when-not-to-use or sibling alternatives, leaving agents to disambiguate against close relatives like nz_lump_sum_tax_calculator and nz_paye_calculator on their own.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources