Calculate.co.nz NZ Calculators

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes well beyond a typical calculator description by noting that BMI is a screening tool, not a diagnosis, does not distinguish muscle from fat, and can misclassify athletic people—instructing the agent to caveat when relevant.

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

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

The description is well-structured and front-loaded: core purpose first, then outputs, usage guidance, unit conversion, and caveats. Every sentence earns its place, and the only overlap with the schema is the Args block, which still adds value through units and examples.

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

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

Since there is no output schema, the description appropriately details return values (BMI value, category classification, healthy weight range) and the exact category names. Combined with conversion constants and the clinical caveat, an agent has everything needed to invoke the tool and interpret its result correctly.

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

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

Schema description coverage is 0%, but the Args section fully compensates by adding units and concrete examples: weight in kilograms (e.g., 75 for 75kg) and height in metres (e.g., 1.75 for 175cm). This removes all ambiguity about parameter meaning and units.

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

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

The description opens with a specific verb and resource: 'Calculate Body Mass Index (BMI) from metric measurements.' It then names the exact outputs (BMI value, category classification, healthy weight range), making the tool's purpose unmistakable and clearly distinct from the sibling calculators.

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

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

It explicitly states 'Use for any BMI question' and provides realistic example prompts like 'what is my BMI' and 'am I a healthy weight.' It also anticipates the main alternative input scenario by explaining exactly how to convert imperial units to metric, so an agent knows when and how to invoke the tool.

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

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

With zero annotations, the description carries the full burden and exceeds it: it discloses that diminishing value front-loads the deduction and never reaches zero by itself, that additional_costs capitalize into the cost base, and that salvage_value floors both methods while the last straight-line year takes only what remains so rounding cannot breach the floor. The 'ONE IMPORTANT LIMIT' paragraph adds a critical caveat that the tool is pure arithmetic, not a tax-rate authority, and warns against presenting invented rates as tax positions. No contradiction with annotations exists because no annotations were provided.

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

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

The definition is long but tightly packed — purpose, routing, method divergence, edge-case behavior, the compliance limit, then Args/Returns — with the critical warning capitalized so a scanning agent cannot miss it. Every block earns its place given 0% schema coverage and no annotations, though the allcaps warning and the partial redundancy between the opening sentence and the 'Use for' list mean it could be trimmed slightly without losing value.

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

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

For a ７-parameter, two-method calculator with no annotations and no output schema, the description covers all grounds: every parameter, conditional requirements, edge-case rounding behavior, the return payload (cost base, depreciable amount, firstyear charge, total charged, closing book value, full schedule), and the compliance boundary. No material gap remains for an agent to call this tool correctly or route users away from it when they need an IRD prescribed rate.

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

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

Schema description coverage is 0%, so the Args block fully compensates: it documents all seven parameters with behavioral meanings — additional_costs as capitalised delivery/installation, salvage_value as a floor, and the two method enum values spelled out. It also adds conditional semantics the schema lacks, namely that useful_life_years is required for straight_line, annual_rate_pct is required for diminishing_value, and years_to_schedule defaults to the life or ten. This is complete compensation for the schema's silence.

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

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

Opens with a specific verb-plus-resource statement — 'Depreciate an asset by straight line or diminishing value, with a year by year schedule' — naming both methods and the output. The 'Use for' examples ('how is depreciation calculated', 'book value after 3 years') remove any ambiguity about which of the sibling calculators is meant. Nothing is a tautology; the tool is immediately distinguishable from all 35 siblings.

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

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

Provides an explicit list of query phrasings to match, then an equally explicit exclusion: the tool is 'the ARITHMETIC of the two methods on a rate you supply' and 'NOT a lookup of Inland Revenue's prescribed rates.' It routes the rate-lookup case to the IRD depreciation rate finder and instructs the agent not to invent a rate — model-level when-to-use / when-not-to-use guidance with a named alternative.

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

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

With no annotations, the description carries the full burden and over-delivers: it names all three formulas (Mifflin-St Jeor, revised Harris-Benedict, Katch-McArdle), discloses formula_spread_kcal and bmr_formula_used in the answer, explains the 7,700 kcal/kg projection assumption, and mandates passing on the caveat that these are population estimates, not a measurement. It also warns about activity-level overestimation and prescribes the two-to-three-week self-correction advice.

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

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

Long, but structured so each block earns its place: purpose, routing examples, formula guidance, input strategy, projection caveats, args, returns. The ALL-CAPS directives front-load the three behaviors that most affect correctness. Only minor redundancy (formulas named in both the guidance and the Returns section) and overall length keep it from a 5.

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

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

For a tool with 8 parameters, zero annotations, zero schema descriptions, and no output schema, the description is complete: full parameter semantics, return contents ('All three BMR formulas with their spread, the TDEE, a calorie target...'), and the caveats to relay to the user. Nothing needed to call it correctly or interpret its results honestly is missing.

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

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

Schema description coverage is 0%, so the Args section must carry the weight, and it does fully: units for age, weight_kg, and height_cm; complete allowed-value sets for activity_level and goal (which the schema lacks enums for); optionality; and behavioral consequences for body_fat_pct ('worth asking for') and target_weight_kg ('produces a timeline'). Every one of the 8 parameters gains meaning beyond the bare schema.

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

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

The opening line states a specific verb and resource: 'Work out maintenance calories (TDEE), BMR, and a target for a goal.' The 'Use for' examples ('how many calories should I eat', 'what is my TDEE', 'calorie deficit to lose weight') make the intended queries unmistakable, and TDEE/BMR/calorie-target clearly differentiates it from bmi_calculator and the NZ-specific calculators in the sibling list.

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

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

Provides an explicit 'Use for' list of example user intents that routes the agent to this tool for calorie and TDEE questions. However, it names no alternatives and states no exclusions (e.g., directing BMI questions to bmi_calculator), so when-not-to-use is left to inference rather than stated.

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

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

With no annotations provided, the description carries the full burden and fully delivers. It states the tool finds pages rather than computes, ranks with 'New Zealand specific pages first', and describes the returned structure: 'ranked list, each with title, url, type ..., category and description.' It also explicitly names limitations, making the behavior transparent beyond the tool name.

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

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

The description is organized into a clear one-sentence summary, usage context, Args, and Returns sections. It front-loads the core behavior, then layers in usage, ranking, and output detail. Every sentence earns its place by providing routing, limitation, or parameter guidance, with no filler or repetition.

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

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

For a simple two-parameter search tool with no output schema, the description is complete. It covers when to use it, when not to use it, ranking behavior, parameter details, and the exact return fields, including the instruction to 'Link the url when recommending a page.' Nothing needed for correct invocation is missing.

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

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

Schema coverage is 0%, so the description is the only source of parameter meaning. It explains query as 'what the user wants to work out, in plain language' and gives a concrete example: natural questions work better than keywords. It also clarifies limit: 'How many results to return, 1 to 20. Default 5.' This adds substantial value over the bare schema.

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

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

The description opens with a specific verb and resource: 'Search all 2,377 Calculate.co.nz calculators, guides and datasets by topic.' It clearly differentiates itself from siblings by stating that only a handful of the site's tools have their own MCP tool and that this one 'searches EVERYTHING' and 'returns the pages that match.' An agent can immediately tell this is a broad search tool rather than a dedicated calculator.

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

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

The description gives explicit when-to-use instructions: 'Use for ANY question of the form ...' and 'whenever a New Zealand calculation is asked about and no specific tool above fits.' It also provides exclusions: 'it does not compute' and 'cannot answer non-New Zealand questions about foreign tax or benefit systems.' This is clear routing guidance against 29 sibling tools.

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

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

With no annotations at all, the description carries full responsibility for behavioral disclosure. It explains the three gaps in the 80% headline, the employer-paid first week, a ceiling, a floor only for full-time earners, rate-register-driven bounds, and the short-term vs 52-week basis.

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

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

Though lengthy, the description is modular: use cases, warnings, boundary logic, and returns. Each paragraph adds a distinct fact needed to use the calculator correctly, and the most important caveat (first week) is emphasized early.

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

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

No output schema exists, but the Returns sentence names all result components: weekly payment, uncapped 80%, bounds, applicability, and employer first-week pay. Combined with the rate-register and basis explanations, an agent has enough to call and interpret the tool correctly.

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

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

The schema gives only types and defaults, so coverage is 0%. The Args section defines each parameter: weekly_earnings as gross pre-injury weekly earnings, hours_per_week with the 30-hour full-time threshold, and basis with explicit short_term and long_term periods.

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

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

The opening sentence identifies the exact resource: 'Estimate what ACC pays each week while an injury stops someone working.' It also gives search-phrase examples that distinguish it from other calculators, so the agent can select it on user intent.

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

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

A dedicated 'Use for' list maps user phrasings to this tool, and the first-week warning tells the agent to lead with that fact for newly injured users. It stops short of naming when not to use the tool or alternative calculators, so I deduct one point.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description fully carries the behavioral disclosure burden. It explains non-obvious calculation traits: the $160 abatement-free zone, the 70% Accommodation Supplement is based on costs above a threshold (not 70% of rent), the 62% board count, area-based caps, Winter Energy Payment conditions, April 1 rate changes, and the estimate-not-assessment caveat. This is exceptionally transparent.

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

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

The description is long but well-structured, starting with a clear purpose, moving through use cases, key calculation factors, caveats, and finally parameter details. Nearly every sentence carries substantive guidance or prevents a common misconception, though a little redundancy exists (e.g., the free zone is mentioned twice), keeping it from a perfect conciseness score.

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

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

The tool is complex with 8 parameters, no output schema, and no annotations, yet the description covers all invocation-relevant details: calculation steps, rate source and verification, seasonal changes, limitations, and return structure ('base rate, abatement, supplement with its cap and entry threshold, winter payment and the total'). Nothing needed to call or understand the result is missing.

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

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

The schema has 0% description coverage, but the description's Args section gives meaningful semantics for all 8 parameters, including calling weekly_income 'other gross weekly income before tax,' noting housing_type 'Board counts at 62%,' and clarifying 'area: 1 being highest cost.' This fully compensates for the bare schema.

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

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

The description opens with a specific verb and resource: 'Estimate a New Zealand main benefit, its abatement and the Accommodation Supplement that goes with it.' It further distinguishes itself from the sibling calculators by naming the exact benefit scenarios and formula components, so an agent can clearly identify this tool.

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

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

The description provides a concrete 'Use for' list with example user queries like 'how much is jobseeker' and 'accommodation supplement how much,' giving clear context for when to invoke it. However, it does not explicitly mention alternatives or when-not-to-use, such as directing tax-related questions to sibling calculators, so it stops short of the 5-level guidance.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description fully carries behavioral disclosure. It warns that cash_difference flatters contracting while package_difference is honest, states annual_contract_income is total invoicing not a rate, explains billable_weeks only yields an implied rate, and calls out GST exclusion plus non-monetary employee rights. This goes far beyond a generic calculator description.

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

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

The description is long but tightly structured: purpose, usage quotes, the central cash-vs-package distinction, parameter meanings, and returns. The capitalised warnings draw attention to the single most dangerous misinterpretation, and every section earns its place given the tool's complexity and the absence of annotations.

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

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

Covers user intent, all parameter semantics, output semantics (two differences, breakeven, which wins, line-by-line costing), and key caveats. Since there is no output schema, the 'Returns' section sufficiently describes the result shape for an agent to select and interpret the tool correctly.

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

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

Schema description coverage is 0%, and the description comphensates with meaningful definitions for all 10 parameters. Notable semantic additions: billable_weeks is 'used only for the implied rate', own_kiwisaver_rate_pct 'applied to both sides', and acc_work_levy_pct is flagged as varying by industry. This avoids serious misuse of the numbers.

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

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

Opens with a specific, distinctive purpose: 'Compare contracting with salaried employment in New Zealand, on what is actually kept.' It also lists natural-language use cases ('should I go contracting', 'contractor rate vs salary') that anchor the tool clearly among the sibling NZ calculators, and the comparison object is unique in that sibling set.

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

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

Provides explicit usage contexts via the 'Use for' block with realistic user queries, and advises leading with breakeven_contract_income when someone is deciding on a rate. It doesnot explicitly name sibling alternatives or state when-not-to-use, but the domain is distinct enough that this is minor.

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

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

No annotations are provided, so the description carries the full burden. It discloses material behavioral traits: region changes the answer significantly (Wellington 34.61c vs Balclutha 48.93c), fixed charges matter, and the output includes biggest_users and a region comparison. The 'Returns:' section further explains what the tool computes. It does not explicitly address side effects, but this is a read-only calculator, so the omission is minor.

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

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

The description is long but well-organized, with a one-line purpose, a 'Use for' list, highlighted behavioral guidance, and clearly labeled Args/Returns sections. It front-loads the core purpose and keeps related information grouped. Some details like exact regional rates add illustrative value but could be trimmed without losing essential guidance.

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

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

With no output schema and no annotations, the description provides a thorough Returns section listing daily/monthly/annual costs, usage vs fixed charge separation, per-appliance costs, biggest users, and regional comparison. It also covers the main decision points for parameter usage. Minor gaps remain, such as the exact semantics of appliance_hours values and what 'the rest' includes, but overall it is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the Args section compensates thoroughly. For each parameter it adds practical meaning: region accepts an 'MBIE survey town, or nz average', household_size is a range with '5 means five or more', daily_fixed_charge is 'In DOLLARS a day', custom_rate_cents is 'in cents per kWh including GST', and appliance_hours lists valid keys like heat_pump and ev_charger. This is exactly the level of detail needed when the schema provides only names and defaults.

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

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

The description opens with a specific verb and resource: 'Estimate a New Zealand household's electricity cost, by region and appliance.' It also provides concrete example queries that distinguish it from sibling calculators like nz_fuel_cost_calculator and bmi_calculator. The scope is immediately clear with no ambiguity about what the tool computes.

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

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

The 'Use for:' section lists realistic user queries and gives contextual guidance like 'Ask for the town' and 'If they have their bill, pass custom_rate_cents...'. It clearly establishes when to use the tool, but it does not explicitly name alternatives or state when not to use it, so it stops 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.

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

With no annotations, the description fully carries behavior disclosure, and it excels: it warns that taxable value is derived from the asset rather than cost, explains the two vehicle valuation methods and their different trajectories, states the days divisor is always 90 per RD 29(5)(a), and cautions that the alternate rate requires a quarter-four wash-up. It also notes that annual_fbt assumes the benefit is unchanged all year. This gives an agent the critical non-obvious rules needed to avoid miscalculation.

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

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

The description is long but deliberately structured into purpose, usage signals, key conceptual warnings, rate caveats, arguments, and returns. Every sentence carries domain-specific value—there is no filler. The most critical pitfalls (days divisor, valuation methods, wash-up) are given prominent placement, and the front-loaded purpose helps an agent quickly categorize the tool.

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

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

For a tool with 10 parameters, no required fields, no output schema, and no annotations, the description is exceptionally complete. It covers all parameter semantics, return values (quarterly taxable value, rate applied, quarterly/annual FBT, wash-up flag, working), and enough legislative grounding to prevent common errors. An agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the 'Args:' section is the only documentation, and it is excellent. It explains each parameter's purpose, which benefit_type it applies to, the required value format (e.g., GST-inclusive cost price, average loan balance, prescribed rate as percentage), and special constraints like days_available capped at 90. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific verb and resource: 'Work out New Zealand fringe benefit tax on a company vehicle, a low-interest loan, or another benefit.' It clearly differentiates this tool from the many NZ calculator siblings by naming the tax domain and the benefit types, leaving no doubt about what the tool computes.

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

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

The 'Use for:' section lists concrete example queries like 'FBT on a company car' and 'how much FBT do I pay', which conveys when the tool is appropriate. It does not explicitly name sibling calculators to avoid or state when-not-to-use, but the context is clear enough that an agent can select it for FBT questions.

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

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

No annotations are provided, so the description carries the full burden of disclosure. It delivers thoroughly: the under-12-months 8% rule, the warning that a payroll leave balance is NOT owed in that case, the note that every figure is GROSS, and the explicit statement of what is excluded from the total. It even describes the return contents. This is far beyond a typical description.

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

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

The description is long but well-structured with clear sections: use-cases, critical first question, branch logic, shared cautions, legal context, args, and returns. The most important instruction ('ASK HOW LONG THEY WORKED THERE FIRST') is front-loaded. Every sentence earns its place; there is no filler or repetition.

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

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

For a complex 9-parameter calculator with no output schema and no annotations, this description is complete. It covers branch selection, parameter requirements, calculation logic, exclusions, gross-vs-net, tax routing, redundancy policy, and what the tool returns. An agent has everything needed to invoke it correctly in its intended situations.

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

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

Schema description coverage is 0%, yet the description's dedicated Args section documents all nine parameters, including units ('leave_balance_days: in DAYS'), mutual exclusivity ('Give this OR hourly_rate'), required conditions ('required for under12'), and optional use cases ('pass it if their pay varied'). This fully compensates for the absent schema-level documentation.

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

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

The description opens with a specific verb and resource: 'Work out a New Zealand final pay: leave payout, notice and redundancy.' It names concrete use-case phrases like 'what should my final pay be' and clearly distinguishes this tool from related siblings by pointing to nz_lump_sum_tax_calculator for the tax treatment. The scope is unmistakable.

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

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

The description gives explicit usage guidance: 'Use for: ...' lists likely user phrasings, then instructs 'ASK HOW LONG THEY WORKED THERE FIRST. It decides the whole calculation.' It explains the two service branches and exactly which parameters to pass for each. It also names the alternative tool for tax ('which is nz_lump_sum_tax_calculator') and clarifies the no-statutory-redundancy rule. This leaves no ambiguity about when to use it.

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

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 substantive disclosures: it warns that l/100km must be converted from MPG or km/L 'or the answer will be confidently wrong,' states that weekly_km=0 returns zero for weekly/monthly/annual figures 'rather than an error,' and reveals the monthly_cost quirk ('a twelfth of the annual figure, not weekly x 4.33'). These are exactly the behavioral traits an agent needs.

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

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

The description is long but every section earns its place: purpose is front-loaded, the IMPORTANT paragraph isolates the single dangerous unit-conversion trap, and Args/Returns/scope are cleanly separated. There is no filler, redundancy is minimal, and the structure makes the critical warnings easy to locate.

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

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

For a 4-parameter calculator with no annotations and no output schema, the description is fully self-sufficient: it covers tool selection, all parameter semantics, the return value set (litres used, trip cost, cost per km, cost per 100 km, periodic costs), the key comparison figure (cost_per_100km), and scope exclusions. An agent has everything needed to invoke it correctly.

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

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 exhaustively. The Args section gives units for all four parameters (kilometres, litres per 100 km, NZD per litre), a realistic price band (2.60–3.00 for petrol in 2026) with guidance to ask the user rather than guess, and the sentinel semantics of weekly_km=0 for one-off trips. This far exceeds the bare schema.

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

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

Opens with a specific verb+resource: 'Work out the fuel cost of a trip, and of regular driving, in New Zealand.' Concrete use cases ('what does it cost to drive Auckland to Wellington', 'is a 6L/100km car worth it over an 9L/100km one') pin down the scope, and the final paragraph distinguishes it from sibling calculators by explicitly carving out road user charges, servicing, tyres, insurance and depreciation.

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

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

States an explicit when-to-use rule: 'Use this for ANY question about what fuel costs: a road trip, a commute, the running cost of a car, or comparing two vehicles.' Also gives when-not-to-use via the scope exclusions, critically 'Not road user charges, which diesel and electric vehicles pay by the kilometre,' which routes the agent toward the sibling nz_road_user_charges_calculator without ambiguity.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses the nine-point NZ scale, the credit-weighted calculation, that failed papers still count credits at zero, and the output structure ('list of objects with grade, points, credits' plus a 'gpa' field). This gives the agent a solid model of the computation and result.

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

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

The description is long but information-dense, with the critical scale warning front-loaded before parameter details. It earns its length given the complexity, though the final sentence about return fields is awkward and suggests possible truncation.

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

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 is thorough: it covers the formula, scale, weighting, parameter formats, and return shape. An agent could invoke this tool correctly without needing additional clarification.

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

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

Schema coverage is 0% and the schema only lists 'courses' and 'scale' without meaning. The description fully compensates: it specifies each course dict needs 'grade' and 'credits', enumerates accepted grade values, and explains the optional 'scale' override format with a 'comma separated list' example.

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

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

The description opens with 'Calculate a grade point average for a New Zealand university' – a specific verb and resource that immediately sets it apart from sibling calculators. It also gives concrete sample queries ('what is my GPA', 'how much will a C drag my GPA down'), making the purpose unmistakable.

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

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

The description explicitly says 'Use for any NZ GPA question' and provides example user phrasings, clearly establishing when to invoke the tool. It adds a when-not warning: 'Do NOT convert to or from a 4.0 scale', which prevents misuse. It does not name alternative calculators, but the scope is unambiguous.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and meets it: it reveals the surprising trait that ALL THREE SPEND LEVELS COME BACK EVERY TIME, explains why annual_gap_basic_to_liberal is the headline figure, and warns that a teenager is not a child-sized cost. These behaviors are completely unobservable from the schema alone.

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

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

The description is long, but the length is earned given zero schema coverage and no annotations: query examples first, then the reasoning behind per-person input, then parameter semantics, then return values. Each paragraph serves a distinct purpose, though the rationale sentences could be trimmed slightly without losing meaning.

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

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

For a tool with 5 parameters, 0% schema description coverage, no annotations, and no output schema, this is exceptionally complete: it lists accepted values for members, diet, and region, defines spend levels and the gap metric, states the include_non_food assumption, and describes the return payload. Nothing an agent needs to invoke it correctly is missing.

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

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, enumerating exact member type strings (child_5_10, teen_11_17, adult_male, adult_female, elderly_65), diet values, region values, and the $25/week meaning of include_non_food. The only gap is that the spend_level input's own accepttable values are implied through the three output levels rather than stated explicitly.

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

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

Opens with a specific verb and resource: 'Work out a weekly grocery budget for a New Zealand household.' It is clearly distinct from the 29 sibling NZ calculators by scoping to grocery budgeting, and it further defines its unique approach by building the household person by person rather than using an average per head.

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

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

Provides an explicit 'Use for:' section with four concrete natural-language query examples ('am I spending too much on food'), giving the agent clear matching cues for invocation. It does not name sibling alternatives or state when-not-to-use, but no sibling tool overlaps with grocery budgeting, so the omission is minor.

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

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

With no annotations provided, the description carries the full behavioral burden and mostly delivers: it explains that mode='add' treats the amount as GST-exclusive while 'remove' treats it as GST-inclusive, and adds rate context (historical 0.125, 0.10 for Australia). It does not disclose rounding behavior or the exact output shape, which is a modest gap for a calculator.

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

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

Purpose is front-loaded in the first sentence, followed by usage scope, examples, and dense parameter documentation in a logical order. The 'Common use cases' list partially overlaps with the earlier use-case enumeration, so it is slightly redundant, but every section serves a purpose and nothing is filler.

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

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

For a 3-parameter calculator with no annotations and no output schema, inputs and intended uses are well covered, but the description never states what the tool returns. The examples ('how much GST is in a $230 total' vs 'remove GST from $1,150') leave ambiguity about whether the result is the GST amount, the adjusted total, or both, and rounding rules are unspecified.

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

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: amount is clarified as 'Dollar amount in NZD,' mode's enum values get operational meaning ('treats amount as GST-exclusive... GST-inclusive'), and gst_rate receives default, historical, and cross-country context. Every parameter gains meaning well beyond the bare schema titles.

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

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

Opens with a specific verb+resource statement — 'Add or remove New Zealand GST (15%) from a dollar amount' — and reinforces it with concrete examples ('what's $500 plus GST', 'how much GST is in a $230 total'). The GST domain is unique among the 29 sibling calculators, so an agent can distinguish it without opening the schema.

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

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

Provides explicit when-to-use guidance: 'Use this tool for ANY question about NZ GST: adding GST to a pre-tax price, extracting GST content from a GST-inclusive total, reverse-calculating GST, or checking GST on invoices and quotes.' It does not name explicit when-not-to-use exclusions, though sibling calculators occupy clearly different domains, making the routing unambiguous.

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

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 rich behavioral disclosure: the net_weekly vs effective_hourly_after_tax distinction (dividing by 52 vs actual hours worked), the decimal-only kiwisaver_rate with 'Passing 3 is rejected', and the 12%-above-threshold student loan repayment. These are precisely the traps an agent would otherwise stumble into. No annotation contradiction exists.

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

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

Approximately 230 words organized into clear sections (purpose, use-for, Args, Returns) with the core sentence front-loaded. The four query examples overlap slightly but each earns its place as pattern-matching signal for an agent.

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

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

For a 5-parameter financial calculator with no annotations and no output schema, the description covers everything required for correct invocation: full parameter semantics, the output shape (gross at each frequency, every deduction, net annual/weekly, effective hourly), and the caveat about interpreting the two weekly figures. The only omission is a tax-year/rates-currency reference, which isn't needed to call the tool correctly.

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

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 covers all 5 parameters with meaning the schema lacks: NZD currency for hourly_rate, '40 is full time in NZ' for hours_per_week, seasonal/academic work guidance for weeks_per_year, the decimal-format rejection for kiwisaver_rate, and the 12% threshold for has_student_loan. Every parameter is semantically enriched.

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

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

Opens with a specific verb+resource: 'Convert a New Zealand hourly rate into a salary, before and after tax.' The stated scope — gross and net at weekly, fortnightly, monthly and annual frequencies plus PAYE, ACC, KiwiSaver and student loan — clearly distinguishes it from single-purpose siblings like nz_paye_calculator or nz_kiwisaver_calculator.

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

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

The 'Use for:' block gives four realistic query patterns ('what is $32 an hour as a salary', 'is $75,000 better than $36 an hour'), giving an agent strong matching signals for when to invoke this tool. However, it never names an alternative or states when NOT to use it — notably it doesn't differentiate from confusable siblings like nz_net_to_gross_calculator or nz_contractor_vs_employee_calculator.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: it discloses the month-by-month compounding methodology, all included factors (contributions, government contribution, fees, PIR tax), the output format (nominal and real balance), current legal rules as of April 2026, and clarifies that PIR is not income tax. This is exceptionally transparent.

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

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

The description is long but well-organized with clear section headers and bullet lists, and it front-loads the purpose and methodology. The length is justified by the 17-parameter surface and the policy rules; only slight redundancy with the schema's default values keeps it from a perfect score.

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

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

Even though there is no output schema, the description explicitly states that both nominal and inflation-adjusted real balances are returned. It covers all parameters, special cases like fund switching, custom return handling, and current contribution/income thresholds. Nothing an agent needs to call the tool correctly is missing.

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

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 comprehensively. The Args section explains all 17 parameters with defaults, allowed values, and conditional requirements (e.g., custom_return_pct required when fund_type='Custom'), plus fund-type return expectations not present in the schema.

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

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

The description opens with a specific verb and resource: 'Project a NZ KiwiSaver balance from current age to retirement age.' The scope is unmistakable and none of the sibling tools cover KiwiSaver, so it is clearly differentiated.

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

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

The description explicitly says 'Use for ANY KiwiSaver retirement-planning question' and gives five concrete example queries, which establishes the intended context clearly. However, it does not name alternatives or state when not to use the tool, so it falls just short of the top score.

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

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

No annotations are provided, so the description carries the full disclosure burden and meets it: it reveals the flat-rate-table calculation method, the NO-ACC and NO-KiwiSaver rules for redundancy/retirement, that kiwisaver_rate is forced to zero for those types, and the 12% student-loan deduction. It also sets expectations for the return ('the rate selected with why_that_rate explaining which row and why, the PAYE, other deductions, and the net amount').

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

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

The structure is strong — use-for queries up front, then critical rules, sibling contrast, args, and returns — and the length is justified for a 5-param tool with no annotations and no output schema. It loses a point for the awkward, ambiguous sibling sentence ('computes the same tax the exact way instead') and the somewhat shouty ALL-CAPS emphasis.

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

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

For a high-complexity calculator with no annotations, no output schema, and 0% schema description coverage, the description covers purpose, method, edge cases, sibling routing, every parameter's meaning, and the return shape. The only omissions (rounding behavior, invalid payment_type handling) are minor and do not impede a correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does for all five: lump_sum is 'the gross lump sum in NZD', payment_type gets its permitted values enumerated (redundancy, retirement, bonus, commission, holiday_pay, exit_inducement, back_pay — the schema has no enum), and kiwisaver_rate is flagged as 'A DECIMAL' with the forced-zero caveat. has_student_loan is tied to the 12% deduction, which the bare schema title does not convey.

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

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

The first sentence names a specific resource and method — 'Tax on a New Zealand redundancy or lump sum, by IRD's rate table' — and the use-for query examples ('how much tax on my redundancy', 'tax on a retirement payment') pin down the intended cases. It further distinguishes itself from nz_bonus_tax_calculator by explaining the two different methods, so an agent can select the right sibling without opening either schema.

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

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

Usage context is explicit: the use-for query patterns tell the agent when this tool applies, and the sibling contrast is unambiguous — 'nz_bonus_tax_calculator computes the same tax the exact way instead, which is roughly where the year-end assessment lands. Both are right; they give different answers. Use this one to check a letter or a payslip.' The 'ALWAYS ask for the annual salary' directive further tells the agent what input to elicit before calling.

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

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: it discloses the exact formula ('standard amortising-loan PMT formula with monthly compounding'), the complete return inventory (monthly/fortnightly/weekly figures, total repayments, total interest, principal/interest shares), and NZ-specific compounding and payment conventions. No contradictions with annotations (none provided).

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

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

Well-structured and front-loaded: the core purpose leads, the Args section is clearly labeled, and the NZ context paragraph earns its place by explaining why weekly/fortnightly payments matter despite monthly compounding. Slightly redundant — the scenario list in paragraph two partially restates the opening purpose — but there is no wasted content.

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

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

With no output schema and no annotations, the description supplies everything needed in one place: parameter semantics, return values, the underlying formula, and domain conventions. An agent can select and invoke this tool correctly without consulting anything else, and the NZ-specific notes make it safe against common misassumptions about rate and term conventions.

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

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: each of the three parameters is documented with units (NZD), format (annual rate as a percentage not decimal, with explicit warning 'NOT 0.065'), and typical values ('whole years', '25 or 30'). The percentage-vs-decimal distinction is exactly the kind of semantic trap that prevents invocation errors.

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

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

States a specific verb and resource — 'Calculate NZ mortgage repayments and lifetime interest totals' — and further scopes to 'ANY mortgage or home loan question.' This clearly distinguishes it from sibling calculators like nz_vehicle_loan_calculator or bmi_calculator by tool name and stated domain.

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

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

Explicitly opens with 'Use for ANY mortgage or home loan question' and lists concrete scenarios (repayment amounts, affordability checks, comparing loan terms, refinance). It does not, however, name excluded cases or point to alternatives such as nz_vehicle_loan_calculator when the loan is not a mortgage.

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

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

With no annotations provided, the description fully discloses the calculator's behavior: it explains the best-80-credits rule, how credits_ignored works, why the GPA and rank score can diverge, and that the GPA is an unofficial convention. This is substantial behavioral context beyond what the schema or annotations could provide.

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

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

The description is long but every section earns its place: purpose, user-intent examples, operational guidance, algorithm note, args, and returns. The critical instruction to lead with next_step is front-and-center, and the structure is easy to scan.

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

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

Despite no annotations and no output schema, the description explains what the tool returns, how the calculation works, which edge cases matter, and what the agent should tell the student first. This is a complete briefing for correct selection and invocation.

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

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

Schema description coverage is 0%, but the description defines all four parameters in the Args section with meaningful distinctions: Level 3 or above credits at Excellence, Merit, Achieved, and attempted-but-not-achieved credits. This fully compensates for the schema's lack of descriptions.

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

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

The description names a specific verb and resource: turning NCEA credits into a University Entrance rank score and an unofficial GPA. It also provides concrete user-phrase triggers and explicitly clarifies that the rank score is the primary output, which sets it apart from sibling calculators like nz_gpa_calculator.

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

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

The description gives a clear 'Use for' list with actual user queries and instructs the agent to always answer with the rank score, even when a GPA is requested. It does not explicitly name alternative tools or state when not to use this calculator, but the intent and selection context are strong.

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

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

With no annotations, the description carries the full burden and meets it thoroughly: it discloses the non-linear relationship caused by progressive tax and the capped ACC levy, states the default deduction assumption (income tax + ACC earner levy only), flags that KiwiSaver/student loan materially change the result, and specifies the return contract including the deductions_included field.

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

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

Longer than average but every block earns its place: purpose, real-world use cases, a critical behavioral caveat, a standing directive, parameter docs, and return contract. The structure is scannable with clear section labels, and the core purpose is front-loaded in the first sentence.

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

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

For a financial tool with no annotations, no output schema, and 0% schema coverage, the description covers everything an agent needs to select and invoke it correctly: purpose, when-to-use, calculation caveats, default assumptions, all parameter meanings, and the output contract. Nothing critical is missing.

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

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

Schema coverage is 0%, so all meaning must come from the description — and all four parameters get substantive explanations. The kiwisaver_rate entry is especially valuable, warning that it is a DECIMAL ('0.035 for 3.5%') to prevent the classic percent-vs-decimal error, and period lists its valid values since the schema defines no enums.

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

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

The first sentence states a specific, directional operation: work out the GROSS salary needed for a given net amount. The 'Use for' examples with realistic queries ('what salary do I need to take home $1,200 a week') make the inverse nature unambiguous, and the framing clearly distinguishes it from forward calculators like nz_paye_calculator and nz_kiwisaver_calculator.

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

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

The 'Use for' block gives explicit, concrete when-to-use context with four realistic query types, and the progressive-tax paragraph warns against the common wrong approach of scaling. However, it never names an alternative tool or states a when-not-to-use condition — sibling differentiation is implied rather than explicit.

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

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

With no annotations, the description carries the full transparency burden and succeeds. It discloses the payment cap, the strategic emphasis on the gap rather than the payment, the eligibility gate with zero payment on failure, the ineligible_reason field, and the KiwiSaver opt-in nuance. It also notes IRD's authority, giving an agent important context about the tool's limits.

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

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

The description is long but well-structured and every section earns its place: purpose, decision-critical guidance, eligibility, args, returns, and exclusions. It is front-loaded with the key instruction to lead with the gap, and formatting makes it easy to scan. No fluff or repetition exists.

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

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 output schema and no annotations, the description is remarkably complete. It covers all inputs, output components, eligibility rules, edge cases, and exclusions. An agent can select the tool, populate parameters correctly, and interpret results including ineligibility and KiwiSaver implications.

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

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

Schema description coverage is 0%, but the Args section comprehensively documents all seven parameters with units, formats, and special rules. For example, annual_income is defined as gross pre-tax NZD, employment_type has explicit values, and kiwisaver_rate is identified as a decimal. This fully compensates for the empty schema descriptions.

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

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

The description precisely identifies the resource and function: New Zealand paid parental leave, including both the payment and the shortfall. It lists concrete user queries, making it immediately clear what the tool does. Its domain is distinct from all sibling calculators, such as annual leave, PAYE, or redundancy, so there is no ambiguity about which tool to invoke.

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

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

The description provides explicit 'Use for' scenarios, covering common questions like 'how much is paid parental leave' and 'can I afford to take parental leave'. It also states clear exclusions (preterm baby payments, keeping in touch hours, partner transfers) and advises how to handle ineligibility. This gives strong when-to-use and when-not-to-use guidance, even without naming a specific alternative sibling.

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses that this is a calculation tool producing a breakdown (income tax, ACC, KiwiSaver, student loan, IETC, net pay) and specifies the ACC capped amount and KiwiSaver minimum rate. It also implicitly signals mutability through parameter defaults. It does not disclose whether it is synchronous or handles edge cases like zero income, but the calculation scope is well covered.

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

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

The description is well-structured with a clear summary, a breakdown of what is returned, usage guidance, exclusions, and parameter documentation. Every sentence earns its place. The use of 'DO NOT use for' is front-loaded and effective.

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

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

Given there is no output schema, the description compensates by listing the full breakdown returned (income tax, ACC, KiwiSaver, student loan, IETC, net take-home pay annual/fortnightly/weekly). It covers the main decision-relevant context: tax year, exclusions, and parameter ranges. It is complete enough for an agent to select and invoke the tool correctly.

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

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 for the schema's bare property titles. It does: it explains annual_income (gross annual salary in NZD, 0 to 10,000,000), kiwisaver_rate (valid values and default), has_student_loan (repaying a NZ student loan), and claim_ietc (eligible for IETC). It adds meaning that the schema lacks, though it could have been even more explicit about the default behavior of claim_ietc since it defaults to true.

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

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

The description opens with a specific verb and resource: 'Calculate New Zealand take-home pay (PAYE) for the 2026/27 tax year'. It clearly distinguishes itself from sibling calculators like nz_net_to_gross_calculator, nz_secondary_tax_calculator, and nz_kiwisaver_calculator by scoping to PAYE take-home pay for the 2026/27 tax year and listing what it returns.

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

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

The description explicitly states 'Use for ANY NZ tax question about: salary, take-home pay, net income, PAYE, KiwiSaver impact, student loan deductions, or IETC eligibility' and explicitly lists exclusions: 'DO NOT use for: self-employed/contractor income, secondary tax codes, non-NZ residents, redundancy lump sums, or pre-April-2026 income.' This gives an agent clear routing guidance relative to sibling tools.

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

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

With no annotations, the description carries full behavioral disclosure and does so richly. It explains payment vs filing deadlines, payer-frequency rules, weekend/holiday shifting, exclusion of regional anniversary days, the paper-filing fallback, and the deliberate error return outside 2026-2027 rather than guessing.

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

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

The description is long but densely informative, with clear sectioning, bolded key warnings, and no filler. Every sentence carries operational value for a complex calculation involving two deadlines, a payer classification rule, holiday shifts, and error behavior.

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

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

Given no output schema and no annotations, the description is remarkably complete. It specifies what will be returned, what fields indicate shifted dates, which years are supported, when an error is returned instead of a guess, and which edge cases are intentionally excluded. An agent has enough context to invoke the tool and interpret the result correctly.

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

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. Each of the three arguments is explained with meaningful semantics: pay_date is the actual payday, annual_paye_and_esct is the threshold-relevant deductions figure, and electronic_filer indicates filing mode. It also explains the critical payer-type threshold rule that gives the annual figure its purpose.

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

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

The description opens with a clear verb and resource: 'Work out when a New Zealand employer must pay PAYE and file the pay run.' It also gives example queries that distinguish this date calculator from siblings like nz_paye_calculator, which is about PAYE amounts rather than due dates.

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

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

The description provides explicit use-for queries and explains when the tool should be invoked. It clarifies that paying and filing deadlines are distinct and that payer type must not be inferred from turnover. However, it does not explicitly name sibling tools that should be used instead for non-date PAYE calculations.

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

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

With no annotations provided, the description carries the full burden, and it steps up meaningfully: it discloses the non-obvious behavior that gross scales linearly while take-home does not, and explains why the Independent Earner Tax Credit defaults on. It also flags the kiwisaver decimal gotcha. The main gaps are the absence of a tax-year basis or estimate caveat and no detail on how the student loan deduction is applied.

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

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

The description is front-loaded with purpose, then usage examples, then a highlighted behavioral insight, so structure guides the agent well. It is slightly longer than strictly needed — the Returns section partly restates 'gross and net' from the opening line, and the use-case list is a bit redundant — but every section does earn its place for a 6-parameter tool.

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

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

For a 6-param calculator with no output schema and no annotations, the description documents all inputs and the full output shape: gross by year, month, fortnight and week, implied hourly rate, and take-home after tax. The only notable absences are an explicit tax-year basis and an estimate disclaimer, but nothing an agent needs to select and invoke the tool correctly is missing.

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

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

Schema coverage is 0%, and the description fully compensates by documenting all six arguments with real semantics. The most valuable entry is 'kiwisaver_rate: A DECIMAL, 0.035 for 3.5%' — exactly the unit trap the schema's plain 'number' type cannot convey. Prose statements such as IETC defaulting on also match the schema defaults, reinforcing correct invocation.

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

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

The opening line states a specific verb and resource: 'Scale a full-time New Zealand salary to part-time hours, gross and net.' The 'Use for' examples with concrete user phrasings like 'what would $90,000 be for 3 days a week' make the tool's job unmistakable. The pro-rata/part-time focus clearly differentiates it from sibling tax and salary calculators such as nz_paye_calculator and nz_net_to_gross_calculator.

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

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

Three concrete use-case phrasings tell an agent exactly which user queries should route here, which is strong context. It also gives explicit conditional advice for the IETC parameter: 'Turn it off for someone on a main benefit, Working for Families or NZ Super.' However, it never names sibling alternatives or says when not to use this tool versus a full-time PAYE or net-to-gross calculator, so it stops short of the top tier.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure — and it delivers. It reveals the critical default behavior ('The default clause here is "none"'), explains that all figures are gross, and clarifies a non-obvious behavioral nuance: total_all_in and total_package differ because notice worked arrives as ordinary salary. It even exposes the tool's deliberate stance against a common jurisdiction error, giving the agent meaningful context about how outputs are computed.

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

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

The description is long but every section earns its place: the legal warning is front-loaded in caps, the two-total distinction is formatted as a scannable list, the tax pointer is one line, and the Args list is compact. Given the 9-parameter complexity and the legal nuance, this length is appropriate rather than bloated. Strong structure with headers and bolded key terms.

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

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

Despite having no output schema, the description summarizes what is returned ('Mandatory entitlements and contractual compensation kept apart, the final pay, and the all-in total') and defines the two headline outputs. It covers prerequisites (checking the employment agreement), edge cases (custom clause), and cross-tool handoffs. For a 9-parameter, legally sensitive calculator, nothing material is missing.

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

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

Schema description coverage is 0% — the schema only has titles and defaults, no property descriptions. The description fully compensates with an Args section that defines each parameter, adds the rule 'Completed years. Part years are not counted' for years_of_service, enumerates all redundancy_clause options, and clarifies that custom_redundancy_amount is used only with 'custom'. This is far more than the schema provides.

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

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

The description opens with a specific verb and resource: 'Work out what is actually owed when a New Zealand role is made redundant.' It clearly differentiates from siblings like nz_final_pay_calculator and nz_lump_sum_tax_calculator by explaining the two totals (total_all_in vs total_package) and explicitly routing tax calculations elsewhere. An agent can immediately identify what this tool does and what it does not do.

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

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

The description provides explicit use cases ('Use for: what redundancy am I entitled to, redundancy pay NZ') and gives a strong when-to-use directive: 'START WITH THIS' for the most common error in general advice. It also tells agents when to quote each total, when to check the employment agreement first, and when to delegate tax computation to nz_lump_sum_tax_calculator. Alternatives and exclusions are handled explicitly, not left to inference.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses fee dependency on block size and purchase method, vehicle-type rate differences, the petrol-hybrid excise distinction, and the heavy-vehicle limitation. It also states what the return includes, which is essential because there is no output schema.

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

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

The description is long but well-structured: purpose, use cases, rate table, fee warning, scope, args, and returns. It is front-loaded and most blocks earn their place. The sentence beginning 'Work out' appears truncated and the all-caps instructional phrases add some noise, so it is not maximally concise.

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

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

Given 5 params, 0% schema coverage, no annotations, and no output schema, this is complete: it covers rates, fees, vehicle-type semantics, exceptions, excluded heavy vehicles, and the return contract. An agent has enough to call it correctly and frame the answer properly.

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

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

Schema description coverage is 0%, but the Args section compensates by explaining each parameter beyond its name: annual_km is Distance driven in a year, vehicle_type lists all values, purchase_method is online or agent, and fuel_efficiency is explicitly 'For the petrol comparison only.' It could add constraints such as positive distances or fee amounts, but the core meaning is present.

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

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

Opens with a specific verb and resource: 'Work out New Zealand road user charges for an EV, diesel or plug-in hybrid.' It enumerates exact vehicle types and rates, so an agent can distinguish it from sibling calculators like nz_fuel_cost_calculator and from generic calculators.

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

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

Provides a 'Use for:' list with common user phrasings such as 'how much RUC will I pay' and 'do hybrids pay RUC', and explicitly excludes heavy vehicles. It doesn't name sibling alternates such as nz_fuel_cost_calculator for when-not-to-use, but the use cases and scope make the routning decision clear.

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

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.

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.

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.

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.

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.

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.

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

No annotations are present, so the description carries the full burden, and it compensates by correcting the misconception that secondary tax is a penalty and explaining that rates include ACC and student loan components. It also tells the agent how to interpret and explain the output, which is behavioral context beyond the schema.

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

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

The description is longer than average, but the extra length earns its place by addressing a widespread misconception and giving agent-facing explanation guidance. The structure is clear: use cases, conceptual correction, parameter list, and return summary.

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

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

With no annotations and no output schema, the description covers the key invocation context: when to use, what to ask for, what each parameter means, and what the response contains. It is not exhaustive, such as lacking an explicit when-not-to-use, but it is sufficient for an agent to select and call the tool correctly.

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

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

Schema description coverage is 0%, but the Args section supplies meaningful descriptions for all four parameters, including the frequency options and student loan effect. It lacks input validations such as positivity or currency, but enough semantics are provided for correct invocation.

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

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

States a specific verb and resource: finding the right New Zealand secondary tax code and what it costs. The 'Use for' examples with concrete user questions make the tool's scope unambiguous and distinguish it from generic tax calculators among siblings.

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

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

Provides explicit trigger phrases for when to use it and instructs the agent to always ask for main job income, since the code depends on both incomes. It does not explicitly list exclusions or alternatives, but the use cases and prerequisites give clear directional guidance.

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

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

With no annotations provided, the description carries the full burden and discharges it exceptionally. It discloses the six-month vesting period, the fact that nothing accrues day by day before that, the ten-day carry-over cap, the twenty-day total cap, and the meaning of capped_by_carry_over_limit / capped_by_total_limit in the output. It also explains that daily_pay valuation is indicative because relevant daily pay is not necessarily salary/260, and that the calculation is the statutory minimum under the Holidays Act 2003 which more generous agreements can exceed.

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

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

The structure is logical and front-loaded: purpose, use cases, critical rules, output hints, then args. The all-caps rule announcement is memorable and the procedural explanation of the caps earns its space. It is long, and phrasings like 'This surprises people who assume leave builds up from day one' and 'because "why is my balance not what I counted" is almost always one of those two' are flavorful but not strictly necessary — minor trimming would tighten it without losing information.

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

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

Given high complexity — six parameters, 0% schema coverage, no annotations, and no output schema — the description is remarkably complete. It covers the statutory rules, the two caps and the flags that report them, the valuation caveat, the contractual-days escape hatch, and a Returns summary listing all output components. The 'Returns:' paragraph is brief, but with no output schema the description still names the key result fields and their semantics.

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

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

Schema description coverage is 0%, so the description must document all six parameters itself, and it does. Each arg gets a plain-language definition that adds meaning beyond type and title: start_date gets an ISO format requirement, as_at gets its default behavior ('Defaults to today'), carry_over_days is clarified as 'before the cap', and extra_contractual_days is tied back to the statutory-minimum explanation in the prose. daily_pay's optionality and purpose are both stated.

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

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

The opening sentence, 'Work out a New Zealand sick leave entitlement and the balance left,' is a specific verb+resource statement that immediately establishes scope. The 'Use for:' query list ('how much sick leave do I get NZ', 'sick leave entitlement', 'can I carry over sick leave') further pins down intent and distinguishes it from calculators like nz_annual_leave_calculator or nz_parental_leave_calculator.

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

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

The 'Use for:' block provides six explicit query patterns that should route the agent to this tool, which is clear context. However, the description never names alternatives or gives exclusions — e.g., it doesn't say to use nz_annual_leave_calculator for annual leave or to use the ACC calculator for work-injury income. Clear context, but no explicit when-not or alternative routing.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains fallback behavior when total_income_all_jobs is omitted, the warning it returns, why ME is not simply 'M plus a credit,' and the student-loan repayment rule on secondary jobs. These are non-obvious behaviors an agent must know to use the tool correctly.

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

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

The description is long, but the content is dense and almost all of it earns its place given the genuine complexity of NZ tax codes. It is structured with 'Use for,' key warnings, Args, and Returns sections, and the most important usage guidance is front-loaded. A slight deduction is warranted for ALL-CAPS prose and some motivational framing that goes beyond strictly necessary operational guidance.

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

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

Despite having no output schema, the Returns section explicitly lists what the caller will receive: the code, its meaning, why it applies over alternatives, the flat rate for secondary codes, and input warnings. Combined with out-of-scope boundaries and per-parameter guidance, the description is complete enough for an agent to invoke the tool and interpret its result correctly.

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

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

Schema description coverage is 0%, but the Args section fully compensates by explaining every parameter beyond its schema type. It clarifies annual_income as 'Income from THIS job, before tax,' total_income_all_jobs as 'Total across every job. Needed for secondary,' and receives_wff_benefit_or_super as removing IETC eligibility. This is precisely the domain context the input schema cannot convey.

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

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

The opening sentence states a specific action and resource: 'Pick the correct New Zealand tax code for an IR330, and explain why.' The 'Use for' examples further clarify the exact user intents it serves, making it easy for an agent to distinguish this from the many other NZ calculator tools.

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

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

The description gives explicit 'Use for' query patterns, tells the agent to always ask for total income, and clearly marks what is out of scope: 'Special tax codes, non-resident status and multiple secondary jobs are out of scope here; those need Inland Revenue.' This provides both when-to-use and when-not-to-use guidance with an alternative path.

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

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly: it explains the refund logic, warns that omitting paye_deducted produces a rougher estimate, flags the ACC-in-PAYE issue, and documents that donations and student loan amounts are returned separately rather than included in refund_or_bill.

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

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

The description is long, but every section earns its place: quick purpose, common use cases, calculation logic, the critical PAYE/ACC request, parameter explanations, and return semantics. Key information is front-loaded and the structured Args/Returns layout makes it easy to scan.

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

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

Given 11 parameters, no output schema, and no annotations, the description is complete: it covers all parameters, return values and their sign convention, which components are included versus separate, approximation caveats, and the salary-and-wages scope.

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

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

The schema has 0% description coverage, and the Args section compensates by adding meaning to all 11 parameters: why months_worked matters, when tax_code is only used, what 'None' means for paye_deducted, and which values are valid for tax_year and secondary_tax_code.

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

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

The opening sentence names the exact verb and resource: 'Estimate a New Zealand income tax refund, or tax owed, for a year.' It clearly distinguishes this end-of-year reconciliation tool from sibling calculators through the refund/end-of-year tax bill framing and concrete use cases.

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

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

It explicitly says to use this for ANY question about a NZ tax refund or end-of-year tax bill and gives realistic common use cases, plus the exclusion 'Salary and wages only.' It does not name sibling alternatives for adjacent cases such as ongoing PAYE or bonus tax, so the guidance stops short of full when-not/alternative routing.

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

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

With no annotations at all, the description carries the full disclosure burden, and it over-delivers: it instructs the agent to lead with interest_share_of_borrowing over the monthly payment and explains why, warns that fortnighly_equivalent is a conversion NOT fortnighly amortisation, demands the excludes caveat before quoting payments, and explains how term-stretching distorts total interest. These are behavioral traits no annotation or schema could convey.

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

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

Purpose is front-loaded, critical behavioral warnings are prioritized before the Args/Returns block, and every paragraph carries non-redundant operational guidance. Minor waste: the use-for list contains two near-synonymous examples ('$35,000 car' and 'car loan calculator'), and the ALL-CAPS emphasis style costs tokens without adding information. Long, but each section earns its place given zero annotations and zero schema coverage.

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

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

For a tool with no annotations, no output schema, and 0% parameter coverage, this description is complete: it states purpose, routing phrasings, output emphasis, comparative-run behavior, fortnighly semantics, standard exclusions, balloon-payment behavior, every parameter's semantics, and the return figures. Nothing an agent needs to invoke it correctly or present its results responsibly is missing.

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

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: annual_interest_rate_pct is disambiguated with 'A PERCENTAGE, so 12.95 not 0.1295' — precisely the format error agents make; deposit is expanded to 'Cash or trade-in up front'; term_years gets its unit made explicit. All four parameters receive meaning beyond the raw schema types and defaults.

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

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

Opens with a specific verb+resource+'Work out repayments on a New Zealand car loan, and what it really costs' — and the 'what it really costs' extension differentiates it from a bare payment calculator. The use-for examples also pin the intended queries ('what would repayments be on a $35,000 car', 'how much interest will I pay on car finance'), which distinguishes it from sibling finance tools like nz_mortgage_calculator and nz_kiwisaver_calculator without opening their schemas.

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

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

Provides an explicit, quoted list of user phrasings that should route here ('car loan calculator', 'is a 5 year car loan a bad idea'), which is strong when-to-use guidance. However, it never names a sibling as the alternative or states when NOT to use it, so an agent facing ambiguous queries like 'loan repayments' has no exclusion signal. This matches 'clear context, no exclusions' exactly.

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

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

With no annotations to carry the burden, the description discloses the non-obvious overnight rule ('a finish time at or before the start is treated as the next day') with a worked example, and the zero-rate behavior. It also states upfront what the tool does NOT compute, which prevents the agent from overpromising results.

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

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

The description is front-loaded with a one-sentence purpose, and every subsequent block earns its place: query examples, the critical overnight edge case, Args, Returns, and exclusions. Clear section headers make it skimmable with no filler.

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

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

This is a moderately complex tool — nested per-day objects, a tricky overnight rule, and multiple output figures — with no output schema and no annotations, yet the description covers inputs, edge-case behavior, and the full return breakdown (per-day hours, total, weekly/fortnightly/monthly/annual gross pay). Nothing an agent needs to call it correctly or set user expectations is missing.

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

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

Schema description coverage is 0% and the schema only declares 'days' as an array with additionalProperties: true, so the Args section is the sole documentation. It fully compensates: per-day key formats ('start'/'finish' as HH:MM 24-hour), optional 'break_minutes' and 'label', the instruction to omit off days, and the semantic of a zero hourly_rate.

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

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

Opens with a specific verb-plus-resource statement — 'Add up a timesheet of work hours, and turn them into gross pay' — and backs it with concrete user queries. Among the large sibling set of NZ calculators, it is clearly the timesheet-to-gross-pay tool, and the closing reference to nz_hourly_to_salary_calculator further draws the boundary.

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

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

Provides an explicit 'Use for' block with four natural-language example queries an agent can match against. It names the alternative for take-home pay (nz_hourly_to_salary_calculator) with the condition that selects it, and the exclusions (overtime, penal rates, public holidays, minimum wage) signal when this tool will not satisfy the user's underlying request.

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

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

With no annotations provided, the description fully carries the behavioral burden and does so impressively. It exposes the no-hours-test rule for IWTC, the need for combined family income, Best Start eligibility up to age 3, the temporary IWTC rate change in March 2027, and the requirement to state which year's answer is being given.

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

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

Though long, every section earns its place: purpose, usage examples, critical corrections, parameter explanations, and return-value contract. The structure is logical and front-loaded with the core purpose and key warnings before the argument list.

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

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

Despite having no output schema, the description's Returns section specifies exactly what the agent can expect: FTC, IWTC, Best Start with abatements, annual/weekly/fortnightly totals, assumptions, and exclusions. Combined with the detailed parameter semantics, an agent has enough context to call the tool correctly and interpret the result.

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

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 for all six parameters. It does: 'children', 'family_income' (combined gross annual), 'children_under_3' (for Best Start), 'iwtc_eligible' (paid work and no income-tested benefit), 'best_start_children_first_year_exempt' (born before 1 April 2026), and 'iwtc_after_march_2027' (reverted $5,070 rate). This adds essential meaning the schema lacks.

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

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

The description opens with a specific verb and resource: 'Work out a New Zealand family's Working for Families entitlement.' It goes further by naming sub-components (FTC, IWTC, Best Start) and example queries, which clearly distinguishes it from the many other NZ calculator siblings.

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

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

The description provides explicit 'Use for' example queries such as 'how much Working for Families will I get' and 'do I qualify for the in-work tax credit'. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough for an agent to route relevant queries here.

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