Skip to main content
Glama

Calculate.co.nz NZ Calculators

nz_schedular_payment_calculator

Work out the withholding tax on a New Zealand schedular payment to a contractor, and what the contractor is actually left with.

Use for: 'withholding tax on contractor payment', 'schedular payment tax
rate', 'IR330C rate', 'director fee tax NZ', 'what tax do I deduct from a
contractor', 'no IR330C what rate'.

TWO RULES CAUSE MOST OF THE TROUBLE.

WITHHOLDING TAX IS CHARGED ON THE PAYMENT EXCLUDING GST. A GST registered
contractor invoicing $1,000 plus GST bills $1,150, and the withholding is
charged on the $1,000. Charging it on the GST-inclusive figure over-deducts
by 15% of the tax every single time, and it is a common payroll error.

THE RATE DEPENDS ON THE ACTIVITY, NOT ON THE CONTRACTOR. Schedule 4 sets a
standard rate per listed activity. A contractor may elect anything between
10% and 40% on an IR330C. WITHOUT THAT FORM THE PAYER MUST DEDUCT AT 45%,
the no-notification rate, which is punitive by design and catches people who
simply never sent the paperwork back. If someone is being deducted 45%, the
fix is usually a form, not an argument.

THE DEDUCTION IS NOT A FINAL TAX. It is a credit against the contractor's
income tax for the year, so a contractor with deductible expenses usually
gets some back and one with a large profit usually owes more.
year_end_credit is the figure that goes in the return. Do not describe the
deduction as "the tax they paid on that job".

Args:
    payment_excluding_gst: The fee BEFORE GST.
    activity: Schedule 4 activity, which sets the standard rate.
    rate_option: standard, nominated (an IR330C election), or no_form.
    nominated_rate_pct: The elected rate, 10 to 40. Required for nominated.
    gst_registered: Whether the contractor is GST registered.

Returns:
    The invoice, the rate and why it applies, the tax deducted, the net to
    the contractor, and the credit claimable at year end.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
activityNostandard_default
rate_optionNostandard
gst_registeredNo
nominated_rate_pctNo
payment_excluding_gstYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden, and it delivers: it discloses the GST-exclusive base rule, the activity-based vs. nominated vs. no-form rate logic, the punitive 45% no-notification rate, and the fact that withholding is a credit, not a final tax. It even warns against mislabeling the deduction.

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?

Though lengthy, every sentence carries critical tax logic that affects calculation results and agent behavior. The use cases are front-loaded, the 'TWO RULES' structure makes key pitfalls memorable, and the parameter definitions are compact. No filler exists.

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?

This is a complex calculator with no output schema, yet the description fully covers inputs, rate-determination behavior, a common error, and the return values (invoice, rate and why, tax deducted, net pay, year-end credit). It even clarifies how to describe the result, making the tool complete for correct invocation.

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%, so the description must compensate, and it does thoroughly. Each parameter is explained with operational meaning: payment_excluding_gst is explicitly 'fee BEFORE GST', rate_option gets its three enum semantics, nominated_rate_pct gets its range and requirement, and gst_registered gets its effect. This goes far beyond the schema's bare titles.

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?

The description uses a specific verb phrase ('Work out the withholding tax... and what the contractor is actually left with') tied to a distinct NZ tax concept (schedular payment). It clearly distinguishes from sibling calculators like nz_paye_calculator or nz_gst_calculator by naming the exact tax domain and target user.

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?

The 'Use for' block gives explicit search phrases and an unambiguous context: when calculating withholding tax on contractor payments. It does not explicitly state when NOT to use this tool or name alternatives (e.g., nz_paye_calculator for employees), so it falls just short of a 5.

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