reference-data

Statutory filing deadlines

get_filing_deadlines

Read-onlyIdempotent

PAID ($0.003, same as any series). Recurring statutory tax deadlines for a country — VAT/GST returns and payments, PAYE/payroll withholding remittances, corporate income tax returns and provisional/instalment payments — as RULES, each cited to the official source with the verbatim phrase that states it, plus the actual DUE DATES in a window, rolled for the country's weekend and national public holidays (every skipped day is listed). Where a rule's source does not say which way a weekend deadline moves, the date is flagged roll_unverified rather than guessed. Countries or taxes we could not verify are returned as a free coverage_gap with reasons, never invented. Pass year_end (MM-DD) to re-anchor corporate-tax rules on the company's own accounting year end. The HTML page /{country}/filing-deadlines shows the rules free. Every AE series is free to try. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.05) on this series so a later gazette does not silently retire the value.

Input Schema

Name	Required	Description
`to`	No	Window end, YYYY-MM-DD. Default from + 365 days; at most 400 days after from
`tax`	No	Only this tax's rules and dates
`from`	No	Window start, YYYY-MM-DD. Default today
`api_key`	No	API key (bypasses x402; metered for invoicing)
`country`	Yes	ISO country code
`year_end`	No	Company accounting year end, MM-DD (e.g. 06-30). Applies to rules marked year_end_variable

Output Schema

Name	Required	Description
`gaps`	No
`unit`	No
`error`	No	Present on a free refusal or error; no charge
`notes`	No
`stale`	No
`value`	No	The rules. Each carries its own source {name, url, anchor} and last_confirmed
`series`	No
`source`	No
`status`	No	On a coverage gap: researched_no_verified_rule or not_yet_researched
`country`	No
`due_dates`	No	Computed occurrences in the window, sorted by due_date
`no_charge`	No
`price_usd`	No
`confidence`	No
`disclaimer`	No
`how_to_pay`	No
`bind_series`	No
`explanation`	No
`label_basis`	No	Inputs and the rule ids that produced the two labels
`x_next_bind`	No
`coverage_gaps`	No	Taxes in scope with no verified rule for this country, and why
`http_endpoint`	No
`coverage_label`	No	How much of the question is covered: ready = complete; partial = held with a disclosed limitation or default; gap = no number served. Rules at /label-rules
`effective_from`	No
`last_confirmed`	No
`confidence_label`	No	Evidence verdict derived from source type, verification age and the stale flag (answers: the weakest series read). Rules at /label-rules
`payment_required`	No	true when the call needs payment; how_to_pay explains x402 or card
`computed_disclaimer`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 17, 2026
- removedOutput schema / properties / label_basis / properties / source_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / label_basis / properties / source_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / label_basis / properties / verification_age_days / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / label_basis / properties / verification_age_days / type
```
Added value: +[
+  "number",
+  "null"
+]
```
AddedOct 13, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent; the description adds valuable behavior beyond that: weekend/holiday rolling with every skipped day listed, roll_unverified flagging when source is ambiguous, coverage_gap for unverified countries, and the after-200 get_changes/register_alert binding for freshness. This goes well past the annotation bar.

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

Conciseness3/5

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

Loads of valuable detail, but pricing ($0.003, $0.05 delivery), free-HTML pointer, and the change-binding sentence make it long and front-loads price before purpose. Efficient for the content it holds, but denser than needed for tool selection.

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?

An output schema exists, so return-value explanation is unnecessary. The description covers semantics an agent needs: rolling behavior, verification flags, coverage gaps, and freshness path – complete for a read tool.

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 coverage is 100% and describes every parameter including defaults and the 400-day cap. The description adds only the year_end re-anchoring rationale and clarifies window semantics implicitly, which is marginal against a fully-documented schema.

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?

Specific verb+resource: returns recurring statutory tax deadlines (VAT/PAYE/CIT) as cited rules plus rolled due dates for a country. Clearly distinguishable from sibling compute_vat/compute_income_tax (which compute amounts) and get_public_holidays (which lists holidays) because it returns rules and dates.

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?

Explains when the paid series is warranted (rolling, citations, coverage gaps) and points to a free HTML alternative plus year_end re-anchoring. Doesn't explicitly exclude the siblings like compute_vat, but the use case is clear.

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

All reference-data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?