Calculate.co.nz NZ Calculators

nz_annual_leave_calculator

Project NZ annual leave balance forward under the Holidays Act 2003.

Calculates hours accrued per week based on the holiday pay rate (8% standard
NZ minimum), then projects the existing balance forward by the requested
future period. Returns projected balance in hours, days, and weeks of
equivalent leave.

Use for any question about: annual leave accrual, future leave balance,
planning time off, calculating entitlement after N months/years of work.

NZ context: Holidays Act 2003 mandates minimum 4 weeks paid annual leave
per year, which equates to 8% of hours worked accruing as leave. Employers
may offer higher rates. Standard NZ full-time week is 40 hours across
5 x 8-hour days.

Args:
    current_balance: Existing leave balance (in hours or days).
    current_balance_unit: 'hours' or 'days'. Default 'hours'.
    hours_per_workday: Standard workday length for this person (default 8).
    holiday_rate_pct: Holiday pay accrual rate (default 8% = NZ minimum).
    hours_per_workweek: Standard work-week (default 40).
    future_period: How far forward to project (default 12).
    future_period_unit: 'weeks', 'months', or 'years' (default 'months').

Input Schema

TableJSON Schema

Name	Required	Default
`future_period`	No
`current_balance`	Yes
`holiday_rate_pct`	No
`hours_per_workday`	No
`future_period_unit`	No	months
`hours_per_workweek`	No
`current_balance_unit`	No	hours

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 1, 2026

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and handles it well: it discloses the computation model (8% of hours worked accruing, then projection), the legal basis (Holidays Act 2003, 4-week minimum), and the return value (projected balance in hours, days, and weeks of equivalent leave). Minor gaps remain around how months are converted to weeks and edge cases like negative balances.

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?

Purpose is front-loaded in the first sentence, followed by method, returns, use cases, and legal context in a logical order. The Args block earns its place given the 0% schema coverage, and the NZ-context paragraph justifies the 8% default. It is somewhat long overall, but every section adds value.

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 7-parameter calculator with no annotations and no output schema, the description covers everything an agent needs: purpose, calculation logic, legal context, parameter semantics with defaults, return format in hours/days/weeks, and usage criteria. The only unspecified details are minor (period-conversion precision, rounding).

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 fully compensates with an Args block explaining all 7 parameters in plain language: units for current_balance, the meaning of the hours-vs-days enum, and what each default represents (8% = NZ minimum, 40h standard week, 8h workday). This adds genuine meaning beyond the schema titles and defaults.

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?

Opens with a specific verb+resource: 'Project NZ annual leave balance forward under the Holidays Act 2003.' It then states the calculation method (8% accrual, projecting forward) and return format (hours, days, weeks), which clearly sets it apart from sibling calculators like nz_parental_leave_calculator and nz_final_pay_calculator.

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 any question about' section listing annual leave accrual, future leave balance, time-off planning, and entitlement after N months/years. This gives clear context for when to invoke it, but it never names alternatives or explicitly states what it is NOT for, leaving some routing decisions to the agent.

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

All Calculate.co.nz NZ Calculators 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.

Resources

Need Help?