malaysia-payroll-mcp

Calculate MTD (PCB) income tax deduction

calculate_mtd

Read-only

Calculates Malaysia's monthly tax deduction (MTD/PCB) for one employee using LHDN's resident formula or the flat 30% non-resident rate, based on fixed salary, EPF and standard reliefs.

Instructions

Works out the monthly tax deduction (MTD, also called PCB) for one employee in Malaysia. For a tax resident it uses LHDN's computerised formula, from the schedule in effect for the pay period, and shows the working; for a non-resident it applies the flat 30%. Fixed monthly salaries and standard reliefs only (individual, spouse, children, EPF, plus a TP1 total); no bonuses or zakat. Include the result's disclaimer in the answer to the user.

Tool call template

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "monthlySalary": "<monthlySalary>",
      "epfEmployee": "<epfEmployee>"
    },
    "name": "calculate_mtd"
  }
}

Input Schema

Name	Required	Description
`children`	No	Qualifying children at RM2,000 relief each: unmarried and under 18, or 18 and over in full-time education below diploma level. Must be 0 in category 1. Defaults to 0. Children in higher education or with a disability (which LHDN counts as 4 or 8) are not supported.
`payPeriod`	No	The calendar month the salary is paid for, as YYYY-MM. It decides which rate tables apply. Defaults to the current month in Malaysia.
`tp1Reliefs`	No	Other reliefs the employee claimed through payroll this month on form TP1 (LP1), in RM. Defaults to 0.
`yearToDate`	No	Required from February. Totals from earlier months of the same calendar year, including any previous employer's (all 0 for someone with no earlier income this year). Or "same_salary_all_year" if every earlier month had this salary and EPF, no TP1 reliefs, and its MTD deducted.
`epfEmployee`	Yes	The employee's EPF contribution this month in RM (the employee share from calculate_epf). 0 if none.
`taxCategory`	No	Required for a tax resident. LHDN tax category. 1: single. 2: married and the spouse has no income (or is jointly assessed). 3: married with a working spouse, or divorced, widowed, or single with an adopted child.
`taxResident`	No	Defaults to true. false if the employee is not resident, or not known to be resident, in Malaysia for tax (usually under 182 days in the calendar year): MTD is then a flat 30% of the salary, with no reliefs, and taxCategory, children, tp1Reliefs and yearToDate are ignored.
`monthlySalary`	Yes	Monthly salary in RM, at most 2 decimal places: basic pay plus fixed allowances. Excludes overtime, commission, bonuses and arrears.

Output Schema

Name	Required	Description
`mtd`	Yes	RM, deducted from pay.
`working`	No	The LHDN formula's working, so it can be checked line by line. Residents only.
`children`	Yes
`citations`	Yes
`payPeriod`	Yes
`disclaimer`	Yes
`yearToDate`	No	The year-to-date figures used, in RM. Residents only.
`explanation`	Yes
`taxCategory`	Yes	null for a non-resident.
`taxResident`	Yes
`monthlySalary`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.0Nov 2, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing that the result includes the working, the flat 30% branch for non-residents (with taxCategory, children, tp1Reliefs and yearToDate ignored), and an obligation to relay the disclaimer. Remaining gaps like rounding of the deduction or error behaviour are minor given the rich schema.

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

Conciseness5/5

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

Three sentences, front-loaded with what the tool computes, then the resident/non-resident branch, then scope limits and the disclaimer instruction. Nothing is redundant with the schema and no sentence is filler.

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

Completeness5/5

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

For a complex domain tool with 8 parameters, an output schema and read-only annotations, the description covers the essential judgement calls an agent needs: which employee type, which reliefs are in scope, what is excluded, and the disclaimer requirement. Return-value detail is correctly left to the output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so each of the 8 parameters is already fully documented including defaults and the 'same_salary_all_year' shorthand. The description only restates the supported relief set and mentions the TP1 total, adding no syntax or format detail beyond the schema. Baseline 3 is the ceiling here.

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

Purpose5/5

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

Names a specific verb and resource ('works out the monthly tax deduction (MTD, also called PCB) for one employee in Malaysia') and pins the computation basis to LHDN's formula. That is clearly distinct from the sibling payroll calculators (EPF, SOCSO/EIS, net pay), so an agent can pick 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.

Usage Guidelines4/5

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

Explicitly scopes applicability: fixed monthly salaries and standard reliefs only, no bonuses or zakat, resident vs non-resident handling. It also tells the caller to surface the disclaimer. It stops short of explicitly naming sisters like calculate_net_pay as the alternative for take-home figures, so it is strong context rather than full when/when-not routing.

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

Deploy Server