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 JP 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

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail beyond them: deadlines are rolled for weekends and national holidays with every skipped day listed, uncertain weekend rolls are flagged roll_unverified rather than guessed, unverifiable countries/taxes surface as coverage_gap with reasons and are 'never invented.' This tells the agent exactly how to interpret output quality and edge cases.

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?

Purpose and behavior are front-loaded, which is good, but the definition is long and carries heavy commercial/CTA content ('PAID ($0.003, same as any series)', 'Every JP series is free to try', 'Register: $0 · Delivery after trial: $0.05') that competes for space with the substantive behavioral facts an agent needs.

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?

With an output schema present, the description need not explain return values, yet it still characterizes the rule/date/flag structure. Combined with 100% schema coverage and annotations covering the safety profile, an agent has everything needed to call this correctly.

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 the schema already documents all six parameters, setting the baseline at 3. The description adds only modest extra meaning, explaining that year_end re-anchors corporate-tax rules on the company's own accounting year end, while from/to/tax/api_key receive no elaboration beyond the 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?

The description names a specific resource (recurring statutory tax deadlines) and enumerates the exact content: VAT/GST returns and payments, PAYE/payroll withholding remittances, and corporate income tax returns/instalment payments delivered 'as RULES... plus the actual DUE DATES.' That level of specificity makes it unmistakable against siblings like get_public_holidays, settlement_date, or compute_vat.

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

Usage Guidelines3/5

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

It gives some routing context (the HTML page /{country}/filing-deadlines shows the rules free; bind get_changes or register_alert after a 200) and tells the agent when to pass year_end. However, it never states when to choose this tool over the many neighboring tax/calendar tools (compute_statutory_interest, get_country_brief, etc.), so usage is implied rather than defined.

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?