sars-dates-mcp

Overview Schema Source Related Servers Discussions Admin

get_upcoming_deadlines

Find South African tax deadlines due within a chosen number of days, optionally filtered by VAT, PAYE, provisional tax, filing season, or EMP501 category.

Instructions

Find South African tax deadlines falling within the next N days.

Use this to answer questions like "what SARS deadlines are coming up?" or "is anything due for VAT in the next month?". Dates come from a curated dataset of SARS filing-season notices and the underlying legislation, not from a live SARS feed.

Args: within_days: How many days ahead to look, counting from today. Both today and the final day are included. For example, 30 covers the next month. category: Optional filter. Must be one of: - provisional_tax: IRP6 provisional payments, provisional taxpayer and trust income tax returns - filing_season: annual individual filing season milestones (auto-assessments, opening dates, ITR12 deadlines) - vat: VAT201 return and payment deadlines - paye: EMP201 monthly PAYE/UIF/SDL declarations - emp501: employer annual and interim PAYE reconciliations Omit it to search across every category.

Returns: One line per matching deadline, sorted earliest first, in the form "YYYY-MM-DD - Title (sars.gov.za, verified YYYY-MM-DD)", each followed by an indented "Note:" line covering edge cases such as weekend or public-holiday shifts. Returns a plain sentence saying so when nothing falls in the window, and an error message listing the valid categories if the category argument is not recognised.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`category`	No
`within_days`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 30, 2026

TDQS

A4.5/5.0

Behavior5/5

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 meets it: it discloses the data provenance (curated SARS notices, not a live feed), exact date-counting semantics, output format and sorting, edge-case notes for weekend/holiday shifts, and error behavior for invalid categories. This gives the agent a rich behavioral picture beyond a bare read-only implication.

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

Conciseness4/5

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

The description is well structured with clear Args and Returns sections and front-loads the purpose. It is slightly longer than necessary because the Returns section partly duplicates information an output schema would already provide, but the added format and edge-case details are still useful.

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?

Given the absence of annotations, a 0% schema coverage, and an existing output schema, the description supplies everything needed to invoke the tool correctly: parameter semantics, data source, output formatting, sorting, and error cases. It is complete for correct use, with only sibling routing left implicit.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate fully and does: it defines within_days precisely (counting from today, inclusive endpoints, example of 30 days) and explains the category enum values in detail, including what omitting it does. No parameter meaning is left to the schema alone.

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

Purpose4/5

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

States a specific verb and resource: 'Find South African tax deadlines falling within the next N days.' The scope and data source are made clear, so an agent can tell it returns upcoming deadlines. However, it does not name or distinguish itself from the sibling tool list_deadlines, which the rubric requires for a 5.

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

Usage Guidelines4/5

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

Provides clear usage context with example questions like 'what SARS deadlines are coming up?' and explains that omitting category searches all categories. It lacks explicit when-not guidance or a named alternative (e.g., list_deadlines), so it falls 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.

Deploy Server