Business-day and public-holiday math for 29 countries: add business days, days between, holidays.
Scored across 5 tools
Each tool targets a distinct operation: date adjustment, date-range counting, holiday listing, business-day checking, and country discovery. There is no overlap in purpose, and the descriptions clearly state the specific output and constraints for each tool.
Most names follow a consistent snake_case verb_noun or query pattern (add_business_days, get_holidays, is_business_day, list_countries). However, business_days_between is noun_phrase style and lacks a clear verb, a minor deviation from the otherwise predictable convention.
Five tools are well-scoped for a business-day and holiday calendar API. Each tool covers a necessary operation without redundancy, and the set is neither too thin nor bloated.
The surface covers the core lifecycle of the domain: discovering supported countries, checking a date, moving by business days, counting ranges, and retrieving holiday details. No obvious operation is missing for a read-only business-day API, and supporting metadata such as regions and year ranges is included.
Add (or, with a negative number, subtract) business days to a date, skipping weekends and public holidays of the country (and region). Returns the result date and the holidays skipped. Read-only. Same engine, cache and limits as GET /v1/add.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Start date, YYYY-MM-DD (2020-2035). | |
| days | Yes | Business days to add; negative counts backwards. | |
| types | No | Optional holiday types that close business days: comma list of public, bank (default: public; "all" = public,bank). | |
| region | No | Optional region/state code for countries with regional holidays, e.g. DE-BY, US-CA (or just BY). | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, DE, GB. See list_countries. | |
| weekend | No | Optional weekend days, comma list of day names like "sat,sun" (default) or "fri,sat", or "none". |
| Name | Required | Description |
|---|---|---|
| date | Yes | |
| days | Yes | |
| region | No | |
| result | Yes | |
| country | No | |
| weekend | No | |
| calendar_days | No | |
| holiday_types | No | |
| result_weekday | No | |
| skipped_holidays | No | |
| skipped_holidays_truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real value: it discloses holiday-skipping behavior, that skipped holidays are returned, and that shared cache/limits apply. It goes beyond the structured safety hints with operational context.
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 compact sentences with the core behavior front-loaded; nothing is wasted. The trailing 'GET /v1/add' reference is slightly cryptic for an agent but does convey engine/cache continuity efficiently.
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 six-parameter date-math tool with an output schema already covering return structure, the description supplies the essential behavioral context (weekend/holiday skipping, negative direction, shared limits). An explicit pointer to sibling tools for adjacent operations is the only meaningful 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 description coverage is 100%, so the schema already documents all six parameters, including the negative-days and holiday-type semantics. The description's mention of negative subtraction and country/region merely reinforces what the schema states, so baseline 3 is appropriate.
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+resource ('add/subtract business days to a date') with the exact mechanic (skipping weekends and public holidays). This clearly distinguishes it from siblings like business_days_between and is_business_day, which count or test rather than offset.
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 implies the subtract use case via negative numbers and orients the agent with 'same engine, cache and limits as GET /v1/add', but never states when to choose this over business_days_between or is_business_day. Usage context is implied rather than explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count business days between two dates in a country (and region), excluding weekends and public holidays. The end date is excluded unless inclusive is true. Returns business, weekend and holiday day counts and the holidays in the range. Read-only. Same engine, cache and limits as GET /v1/between.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End date, YYYY-MM-DD (2020-2035). | |
| from | Yes | Start date, YYYY-MM-DD (2020-2035). | |
| types | No | Optional holiday types that close business days: comma list of public, bank (default: public; "all" = public,bank). | |
| region | No | Optional region/state code for countries with regional holidays, e.g. DE-BY, US-CA (or just BY). | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, DE, GB. See list_countries. | |
| weekend | No | Optional weekend days, comma list of day names like "sat,sun" (default) or "fri,sat", or "none". | |
| inclusive | No | Count the end date too (default false). |
| Name | Required | Description |
|---|---|---|
| to | Yes | |
| from | Yes | |
| region | No | |
| country | No | |
| weekend | No | |
| holidays | No | |
| inclusive | No | |
| holiday_days | No | |
| weekend_days | No | |
| business_days | Yes | |
| calendar_days | No | |
| holiday_types | No | |
| holidays_truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds the end-date/inclusive boundary rule, the returned components (business, weekend, holiday counts plus holiday list), and a note about shared engine, cache and limits. The only weakness is that 'limits' is left undefined.
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?
Four short sentences, front-loaded with the core purpose before the boundary rule and the return/limit notes. The trailing reference to 'GET /v1/between' is slightly off-target for an agent but costs little.
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 7-parameter tool with an output schema, the description covers purpose, boundary semantics, and return content, so an agent can call it correctly. Minor gaps remain around what 'limits' means and error behavior, but return-value details are rightly left to the output schema.
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 country, region, types, weekend, from/to and inclusive are all documented in the schema. The description only reinforces the inclusive flag's effect on counting, adding little beyond the schema text — baseline 3 is appropriate.
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 ('Count business days between two dates') with explicit scope ('in a country (and region), excluding weekends and public holidays'). This clearly separates it from siblings like is_business_day (single-day check), add_business_days (date arithmetic), and get_holidays (holiday listing).
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 when the tool applies ('between two dates') and clarifies the end-date exclusion rule, but it never names an alternative or states when NOT to use it. An agent choosing between this and get_holidays or add_business_days gets no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the public (and optionally bank/observance) holidays for one country (and region) in one year, 2020-2035, with local names, types and official source links. Read-only. Same data, cache and limits as GET /v1/holidays.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Year, 2020-2035. | |
| types | No | Optional comma list of public, bank, observance, or "all" (default: all). | |
| region | No | Optional region/state code for countries with regional holidays, e.g. DE-BY, US-CA (or just BY). | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, DE, GB. See list_countries. |
| Name | Required | Description |
|---|---|---|
| year | Yes | |
| count | Yes | |
| notes | No | |
| scope | No | |
| region | No | |
| country | Yes | |
| sources | No | |
| holidays | Yes | |
| region_name | No | |
| country_name | No | |
| data_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and 'Read-only' in the description is largely redundant. The description does add some behavioral context by flagging that caching and limits exist, but the reference to 'GET /v1/holidays' is a pointer rather than a concrete disclosure of what those limits are.
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 compact sentences, front-loaded with purpose and scope, then reader-facing notes. The only wasted clause is 'Read-only', which duplicates readOnlyHint=true already exposed in annotations.
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?
An output schema exists, so return values need not be explained, and the description covers the key constraints: one country, optional region, single year, bounded range, and selectable holiday types. The only omission is any note on how regional holidays combine with country defaults, which the schema only partially implies.
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% (year range, ISO alpha-2 country, region code examples, types comma list all documented in-schema), so the schema carries the parameter burden and baseline is 3. The description only restates the year range and country/region relationship, adding no format or interaction detail beyond 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?
States a specific verb and resource ('List the public ... holidays'), plus the exact scope: one country, optional region, one year, bounded 2020-2035. The declared return contents (local names, types, official source links) further pin down what the tool produces, and no sibling tool (business-day math, country listing) overlaps with it.
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 rather than stated: the description notes holidays can optionally include bank/observance types, which nudges toward the 'types' parameter, but there is no explicit when-to-use or when-not-to-use guidance. Given the siblings are arithmetic utilities rather than holiday alternatives, this is adequate but leaves the call/no-call decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a date is a business day in a country (and region), considering weekends and public holidays. Returns the reason (weekend or holiday name) plus the previous and next business days. Read-only. Same engine, cache and limits as GET /v1/is-business-day.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date to check, YYYY-MM-DD (2020-2035). | |
| types | No | Optional holiday types that close business days: comma list of public, bank (default: public; "all" = public,bank). | |
| region | No | Optional region/state code for countries with regional holidays, e.g. DE-BY, US-CA (or just BY). | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. US, DE, GB. See list_countries. | |
| weekend | No | Optional weekend days, comma list of day names like "sat,sun" (default) or "fri,sat", or "none". |
| Name | Required | Description |
|---|---|---|
| date | Yes | |
| reason | Yes | |
| region | No | |
| country | No | |
| holiday | No | |
| weekday | No | |
| weekend | No | |
| business_day | Yes | |
| holiday_types | No | |
| next_business_day | No | |
| previous_business_day | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so safety is covered. The description's one added behavioral note—'same engine, cache and limits as GET /v1/is-business-day'—hints at caching and rate limiting but is vague and never quantifies them. 'Read-only' merely repeats the annotation.
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?
Purpose is front-loaded in the first sentence with no wasted preamble, and the whole description is three tight sentences. Minor slack comes from 'Read-only' (redundant with annotations) and an HTTP endpoint reference of limited value to an agent choosing a tool.
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 an output schema present, the description needn't explain full return values, and annotations carry the safety profile; the description stays within its lane and covers scope adequately. It is nearly complete, only slightly under-specified on the caching/limits it alludes to.
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 all five parameters are self-documented with formats, patterns and defaults. The description only broadly gestures at country/region and weekends/holidays, adding no syntax or constraint detail beyond the schema, so 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?
States a specific predicate verb and resource: checking whether a given date is a business day, scoped by country and region. This is distinguishable from the arithmetic siblings (add_business_days, business_days_between), but the description never names those alternatives to reinforce the distinction.
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 explains the domain (weekends and public holidays) but gives no when-to-use guidance and never contrasts itself with siblings like business_days_between or get_holidays. An agent must infer that this is the single-date predicate tool from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the supported countries (ISO codes), their regions and the supported year range. Read-only. Same data and limits as GET /v1/countries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| years | No | |
| countries | Yes | |
| data_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' in the description is pure duplication and earns no credit. The only genuinely new behavioral claim is 'same data and limits as GET /v1/countries', which gestures at rate/size limits without stating them. Adds a little beyond the structured fields, but not much.
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 short sentences, front-loaded with the resource and its contents. The second sentence's 'Read-only' clause duplicates the annotation and does not earn its place, but the cost is only two words. The API-path reference is a compact way to signal parity with a known endpoint.
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 no-parameter, read-only enumeration with an output schema (so return values need no explanation) and full annotation coverage, the description is nearly sufficient. Its one soft spot is the vague 'same data and limits as GET /v1/countries' — an agent with no REST context cannot resolve what those limits are.
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?
The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add or omit. Nothing in the description is needed here.
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 (List) and resource (supported countries) and enumerates the payload contents: ISO codes, regions, and the supported year range. The sibling set (add_business_days, business_days_between, get_holidays, is_business_day) has no overlapping function, so no sibling disambiguation is required. An agent knows exactly what this returns 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?
There is no explicit 'use this when' statement and no alternatives to compare against, but the listed contents (ISO codes, year range) make the purpose obvious: validating inputs for the holiday/business-day siblings. Usage is implied rather than stated, which lands at the minimum-viable level.
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.
add_business_daysbusiness_days_betweenget_holidaysis_business_daylist_countriesPublic holidays for 150+ countries, business-day maths and timezone lookup
Public holidays and working-day maths for 200+ countries, cross-checked across three providers.
US federal holidays, business-day maths, invoice due dates and IRS deadlines.
Business days, holidays and settlement dates for ACH, TARGET2, Bacs, 28 exchanges and 247 countries
Add one secure layer between your agents and this server.