Skip to main content
Glama

Public Holidays API - 150+ countries and their states/regions

public_holidays
Read-onlyIdempotent

Official public holidays for a country (and state/province/region) for any year 1950-2100: date, name, weekday. Local-language names where available (language=de, fr, bg...). Maintained open-source holiday rules, no outside call, < 50 ms. Free: 25 calls/day per IP. Paid: $0.001 per call via x402 at https://radarbg.com/x402/public-holidays.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "year": 2026,
      "country": "DE",
      "subdivision": "BY"
    },
    "name": "public_holidays"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoYear, default this year
countryYesISO 3166 alpha-2 code, e.g. DE, BG, US, GB
languageNoName language, e.g. en, de, fr (if the country has it)
subdivisionNoState/region code, e.g. BY (Bavaria), CA (California)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / year / minimum
      Added value: +0
  2. First observed

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, and open-world, so the description's marginal contribution is the operational context: local rule data with "no outside call," sub-50 ms latency, 25 free calls/day per IP, and $0.001 per call via x402. That rate-limit and cost disclosure is genuinely useful for an agent deciding on batching or retries. It does not describe response shape, empty-result behavior (e.g., country with no subdivision support), or what happens to out-of-range years, which keeps it at a 3.

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?

Three dense, front-loaded sentences: purpose and return fields first, then language coverage, then provenance/performance/pricing. Every clause carries information; the only cost is that pricing and latency details are compressed into the final sentence, making it slightly cramped.

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

Completeness4/5

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 names the returned fields (date, name, weekday) and adds coverage range, data provenance, latency, and rate limits/pricing, which is enough to plan calls. It is slightly thin on error/invalid-subdivision behavior and on how holidays are returned for multi-day or multi-region cases.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description earns an upgrade by constraining the year to 1950-2100 even though the schema only declares minimum 0, and by clarifying that language selection depends on country availability. It does not clarify subdivision code validity (ISO 3166-2 suffix only, no country prefix) beyond the schema's examples.

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+resource: "Official public holidays for a country (and state/province/region) for any year 1950-2100: date, name, weekday." An agent immediately knows the payload and granularity. It stops short of naming a differentiating sibling (e.g., business_days for working-day math), so a 4 rather than 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 Guidelines3/5

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

Usage is implied by the scope statement (need holidays for a country/subdivision/year) and the language and year-range qualifiers, but there is no explicit when-to-use/when-not guidance or pointer to an alternative such as business_days for working-day calculations. The agent must infer the fit from the scope sentence alone.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources