SA payroll and labour rules: minimum wage, BCEA overtime, UIF, SDL, public holidays, leave
Scored across 7 tools
Each tool has a clearly distinct purpose: date counting, leave/termination rules, minimum wage, overtime premiums, public holidays, UIF/SDL, and feedback. Overlap between business_days_between and public_holidays is complementary rather than ambiguous.
All names use consistent snake_case and are descriptive noun phrases, which makes the set predictable. However, most names are noun-centric rather than action-oriented, and unmet_request deviates slightly from the payroll-calculation pattern.
Seven tools is well-scoped for a focused South African payroll and labour rules server. Each tool earns its place without excessive breadth.
The core BCEA/NMW/UIF/SDL areas are covered, including leave, notice, severance, overtime, public holidays, and minimum wage. Minor gaps remain around PAYE/income tax and broader payroll administration, but agents can work around them for the stated rules-focused scope.
Counts South African working days between two dates (inclusive), excluding weekends and public holidays. Optionally counts Saturdays as working days. Useful for notice periods, payment terms and delivery dates.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | YYYY-MM-DD | |
| start | Yes | YYYY-MM-DD | |
| include_saturdays | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real substance beyond that: the South African holiday calendar, inclusive date boundaries, and the Saturday toggle. It omits what the response looks like — there is no output schema, so an agent cannot know whether it receives an integer count or a breakdown — which keeps it from a 5.
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?
Three short sentences, front-loaded with the counting rule and then the Saturday modifier and use cases. Nothing is redundant and no sentence repeats a structured field verbatim.
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 three-parameter read-only calculation, the description covers jurisdiction, inclusivity, holiday handling, and the Saturday flag. The remaining gap is the return shape (integer count vs. list of days), which matters more than usual because no output schema exists.
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 67%, with include_saturdays documented only as a bare boolean, and the description supplies the missing meaning ('counts Saturdays as working days'). 'Inclusive' also clarifies how start and end are treated in a way the schema's 'YYYY-MM-DD' descriptions do not.
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 precise verb and resource ('Counts South African working days between two dates'), plus the defining rule set: inclusive boundaries, weekends and public holidays excluded. That scope also separates it from the sibling public_holidays tool, which would surface the holiday data this tool consumes.
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 sentence 'Useful for notice periods, payment terms and delivery dates' gives situational context that implies when to reach for it. It does not state exclusions or point at an alternative (e.g. 'use public_holidays to see which holidays were excluded'), so the guidance 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.
Returns BCEA minimum leave (annual, sick, family responsibility), notice period and retrenchment severance pay for an employee, given days worked per week, start date and pay.
| Name | Required | Description | Default |
|---|---|---|---|
| as_at | No | Date to evaluate, default today | |
| start_date | Yes | Employment start, YYYY-MM-DD | |
| weekly_wage | No | Ordinary weekly wage in rand (for severance) | |
| worker_type | No | general | |
| days_per_week | Yes | Days worked per week, e.g. 5 or 6 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds that severance depends on pay and that entitlements depend on days per week and start date. It does not disclose output shape, defaulting behavior for as_at, or jurisdiction caveats, but adds real context beyond the annotations.
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?
A single front-loaded sentence that names the resource, the outputs and the required inputs with no filler. Nothing could be removed 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?
No output schema exists, so the description must convey return values — it does by enumerating the three computed areas. Combined with a high-coverage input schema, an agent has enough to call it correctly, though a note on units/format of the leave and notice values would close the remaining gap.
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 80%, so the schema already documents each parameter including the worker_type enum and as_at default. The description only reinforces that days_per_week/start_date drive leave and notice while pay drives severance, adding marginal meaning beyond the schema — baseline 3.
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?
Specific verb ("Returns") plus an enumerated list of the exact outputs (annual/sick/family-responsibility leave, notice period, severance pay) and the inputs that drive them. The domain is clearly distinct from siblings like minimum_wage_check or overtime_and_premium_pay, so an agent can select 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?
Usage is implied by naming the BCEA entitlements, but there is no explicit statement of when to prefer this tool over e.g. minimum_wage_check or uif_sdl_contributions, nor any exclusions or prerequisites. Adequate but leaves routing to inference from the topic names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks whether an hourly, daily, weekly or monthly wage meets South Africa's National Minimum Wage on a given date (farm and domestic workers included). Returns the legal minimum, the shortfall and monthly equivalents.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | YYYY-MM-DD, default today | |
| amount | Yes | Wage in rand | |
| period | Yes | ||
| worker_type | No | general | |
| hours_per_day | No | Ordinary hours per day (needed for day). Default 9 | |
| hours_per_week | No | Ordinary hours per week (needed for week/month). Default 45 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds that it returns the legal minimum, the shortfall and monthly equivalents, which is valuable since there is no output schema. It stops short of disclosing how the date maps to rate-table versions or whether non-compliant results are flagged as errors.
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?
Two sentences, front-loaded with the check and scope, then the return payload. No filler, no restatement of the title.
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, the description correctly covers the return values, and it identifies the jurisdiction and worker categories. It is slightly thin on rate-versioning behaviour for the date parameter and on the unexplained epwp worker type, but an agent has enough 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?
At 67% schema coverage the schema already documents date, amount, hours_per_day and hours_per_week, and the description's mention of day/week/month periods and 'farm and domestic workers included' loosely reinforces period and worker_type. However, it never explains the 'epwp' enum value or why hours_per_day/hours_per_week matter, so it adds only marginal meaning over 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?
Names a specific verb (checks) and resource (wage against South Africa's National Minimum Wage) with the exact dimensions supported (hourly, daily, weekly, monthly) and the jurisdictional scope. This clearly separates it from siblings like overtime_and_premium_pay and uif_sdl_contributions, which address different payroll computations.
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 is only implied: an agent can infer this is the compliance-check step before running premium pay or contributions calculations. There is no explicit when-to-use statement, no exclusions (e.g. non-SA wages, future-dated rates), and no pointer to a sibling tool for related questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists South African public holidays for a year, including Sunday-to-Monday substitutions and once-off declared holidays (e.g. election days).
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | e.g. 2026 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral detail beyond that: Sunday-to-Monday substitution rules are applied and once-off declared holidays such as election days are included, which tells the agent what to expect in the payload. It stops short of stating coverage limits for historical or future years.
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?
One sentence, front-loaded with the resource and scope, with the qualifying detail about substitutions appended where it belongs. 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?
With no output schema, the description must convey what comes back, and it does so at a high level: holidays for the year including substitution dates and once-off declarations. It leaves the exact return shape (names, dates, whether substitution provenance is flagged) unspecified, which is a minor gap for a tool this simple.
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?
There is a single parameter with 100% schema description coverage, so the schema already carries the burden. The description only repeats the 'for a year' framing and adds no format constraints or valid-range guidance beyond the schema's 'e.g. 2026'.
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 ('Lists South African public holidays') plus the scope ('for a year'), which is unambiguous. It does not name or contrast itself against siblings like business_days_between, though their functions are distinct enough that confusion is unlikely.
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 is only implied: an agent infers this is the tool to call when it needs the holiday calendar, likely as input to business_days_between. There is no explicit when-to-use statement, no mention of alternatives, and no note on which years are supported.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculates monthly UIF (1% employee + 1% employer, capped at the R17,712 ceiling) for one or more employees, and the employer's Skills Development Levy (1% of payroll, exempt if annual payroll is under R500,000).
| Name | Required | Description | Default |
|---|---|---|---|
| monthly_remuneration | Yes | Gross monthly remuneration per employee, in rand | |
| annual_payroll_estimate | No | Employer's total annual payroll, for the SDL exemption test. Default: monthly total x 12 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuine behavioral rules — the 1%+1% split, the rand ceiling on UIF, and the payroll threshold that nullifies SDL. It omits how the cap is applied per employee per month and mentions nothing about rounding or what the result contains, keeping it below a 5.
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?
One dense sentence, front-loaded with the tool's purpose, with the parentheticals carrying the rates and thresholds that an agent actually needs. No filler, no repetition of the title or schema.
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 only two parameters, full schema coverage, and read-only annotations, the description covers input semantics and computation rules well. The remaining gap is output shape — with no output schema, the agent is not told whether the response lists UIF employee/employer and SDL amounts per employee.
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 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining why annual_payroll_estimate exists (the SDL exemption test) and that remuneration is per-employee with a statutory cap applied. It stops short of clarifying whether the array is processed independently per element or aggregated.
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 (calculates) and two named resources (UIF and SDL) with the exact rates, the R17,712 cap and the R500,000 exemption threshold, so scope is unambiguous. It is clearly separable from all siblings, which cover dates, leave, wages, overtime and holidays rather than statutory contributions.
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 implies the usage context (monthly payroll contributions for one or more employees) but never states when to call this versus alternatives or what to do when only a subset of employees is relevant. There are no exclusions, preconditions, or routing hints — the agent must infer that this is the payroll-contribution calculator.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free to call. If you needed South African data that none of these tools provide (a cost, rate, rule, price or place we don't cover), describe it here in one sentence. We review these every week and build the most-requested data first.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | What information you were looking for, in one sentence. | |
| region | No | Optional: province or town, if it matters. | |
| context | No | Optional: the kind of task it was for, e.g. 'renovation quote' or 'payroll run'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds real context beyond the annotations: 'Free to call' signals no call-budget cost, and 'We review these every week and build the most-requested data first' discloses that this is an asynchronous request with no immediate data returned. Nothing contradicts readOnlyHint=false (a submission does create a record) or openWorldHint=false; auth and rate-limit details are absent but low-risk here.
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?
Two sentences, front-loaded with the cost signal and then the qualifying condition, then the outcome. No restatement of the tool name and no wasted clauses.
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 fully documented, no-output-schema submission tool, the description covers purpose, trigger and what happens after submission. It could be slightly more complete by stating that no data is returned synchronously, but the weekly-review sentence conveys that implicitly.
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 100%, so the schema already explains need, region and context fully. The description reinforces the one-sentence constraint on the required field but adds no meaning beyond the schema for the optional region and context parameters, so the baseline 3 applies.
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 states a specific action (describe a missing data need) and resource (South African cost, rate, rule, price or place not covered), and explicitly frames itself as the fallback when the sibling calculators don't cover a need. It is immediately distinguishable from bond_repayment, municipal_rates and the other siblings, which are lookups rather than submissions.
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 gives a clear trigger: use this when needed South African data is not provided by 'none of these tools,' and enumerates the kinds of gaps that qualify. It does not name the specific sibling domains, so an agent still has to reason about what the siblings already cover before deciding to fall back here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
business_days_betweenleave_and_terminationminimum_wage_checkovertime_and_premium_paypublic_holidaysuif_sdl_contributionsunmet_requestSouth African business days, public holidays and SARS EMP201/VAT201 deadlines.
South African property costs: transfer duty, buying costs, bond repayments, municipal rates
South African building and renovation cost estimates in rand, by region and finish quality
UAE and Saudi gratuity, leave, notice, overtime and sick-pay arithmetic with cited articles.
Add one secure layer between your agents and this server.