Skip to main content
Glama
qinisolabs

bizdays

by qinisolabs

bizdays

Verified business-day math for AI agents — holidays + per-country weekends, not guesses.

Verified, trustworthy data tools for AI agents. "Qiniso" means "truth" in Zulu.

Website · npm · MCP endpoint · MCP Registry


LLMs answer "what date is 5 business days after Dec 22nd in the UK?", "how many working days are in this month?", and "is Friday a working day in Saudi Arabia?" confidently and often wrongly — they miscount, forget public holidays, and assume every country's weekend is Saturday/Sunday. bizdays gives an agent the deterministic answer from real public-holiday calendars and per-country weekend rules, showing the weekend rule and the exact holidays it skipped.

Two things break naive business-day math, and bizdays fixes both: weekends aren't Sat/Sun everywhere (Fri/Sat in Saudi Arabia, Egypt & Israel; Fri in Iran; Sun in India; Sat/Sun in the UAE since 2022), and "holiday" must mean a real day off — off-the-shelf data counts observances like Valentine's Day and Christmas Eve, which are not days off.

Counting the working days in a month, a frontier LLM with no tools is wrong 63% of the time, cold — and 23% across business-day questions overall. bizdays: 0%.

Add it to Claude

Settings → Connectors → Add custom connector, and paste — no login, no key:

https://bizdays.qinisolabs.workers.dev/mcp

Stateless, reads no user data, requires no secrets. Prefer to run it locally over stdio? Add { "command": "npx", "args": ["-y", "@qinisolabs/bizdays"] } under mcpServers in your client config.

Related MCP server: business-day-mcp

Use it as a library

Every tool is also a typed function — no MCP required:

npm i @qinisolabs/bizdays
import { addBusinessDays, countBusinessDays, isBusinessDay } from "@qinisolabs/bizdays";

addBusinessDays("2025-12-22", 5, "GB").result;       // "2025-12-31" (skips Christmas + Boxing Day)
countBusinessDays("2025-12-01", "2025-12-31", "US"); // { businessDays: 22, ... }
isBusinessDay("2025-06-13", "SA").isBusinessDay;      // false — Friday is weekend in Saudi Arabia
isBusinessDay("2025-02-14", "US").isBusinessDay;      // true  — Valentine's Day is not a public holiday

Every function returns a rich result: the answer, the weekday, exactly which weekends and named holidays were skipped, the weekend rule and its source, and a confidence flag.

What it does — 6 tools

Tool

What it answers

add_business_days

What date is N working days from a start date? (N may be negative)

count_business_days

How many working days between two dates? (endpoints inclusive by default)

is_business_day

Is this date a working day? If not, why (weekend / public holiday with its name)?

next_business_day

First working day strictly after a date

previous_business_day

Last working day strictly before a date

country_rule

The weekend rule + its source, whether holidays apply, and a confidence flag

Public holidays for 206 countries (and subdivisions) come from date-holidays, filtered to type: "public". Weekends come from Unicode CLDR via the runtime Intl API, plus a curated data/weekend-overrides.json correction layer (e.g. Bangladesh Fri/Sat, Nepal Sat-only) — the maintained data is the moat.

What it is not

  • Not all-holidays. It counts weekends and public holidays only — not regional or optional observances. Pass company shutdowns or regional days via extraHolidays.

  • Not uniformly verified. A Tier-1 set of ~65 countries is verified; others work but are flagged unverified. Where no holiday calendar exists (e.g. Qatar, Kuwait, Oman), the correct weekend still applies and the response says so (holidaysApplied: false).

  • Not a live service dependency. The library makes no network calls; dates are YYYY-MM-DD in UTC.

Architecture

A single TypeScript package exposing one MCP server over two transports — stdio (local / npx) and a Cloudflare Worker (the hosted edge endpoint) — both driven by the same core.ts tool definitions, which also power the importable library.

npm install
npm run build
npm test

Privacy

This tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. All reference data is bundled — no network calls, and nothing leaves your device. Full policy: https://qinisolabs.github.io/privacy.html.

License

Apache-2.0. Bundled holiday data is from date-holidays (ISC AND CC-BY-3.0); see NOTICE.

Available Tools

6 tools
add_business_daysA

USE THIS to compute a deadline or settlement date instead of counting on your fingers — never guess what date is N working days away. Adds (or subtracts, if N is negative) business days to a start date, skipping that country's weekends AND its public holidays. Weekends are country-correct (e.g. Friday/Saturday in Saudi Arabia, Saturday/Sunday in the UAE) and only real public holidays are skipped — not observances like Valentine's Day. Returns the result date, its weekday, and exactly which weekends/holidays were skipped.

ParametersJSON Schema
NameRequiredDescriptionDefault
startYesStart date, YYYY-MM-DD.
daysYesBusiness days to add; negative subtracts.
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.
extraHolidaysNoOptional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day.

TDQS

A4.7/5.0
Behavior5/5

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

Given no annotations, the description fully reveals behavior: it handles negative values, adjusts weekends per country (e.g., Friday/Saturday in Saudi Arabia), skips only real public holidays not observances, and returns result date, weekday, and skipped weekends/holidays.

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

Conciseness5/5

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

The description is two sentences, front-loaded with 'USE THIS', and contains no redundant information. Every clause adds meaningful context.

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 no output schema and four parameters, the description covers all essential aspects: purpose, input parameters, behavior (weekends, holidays, negative days), and output. It is fully adequate for an agent to select and invoke the tool correctly.

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 baseline is 3. The description adds value by explaining country-specific weekend behavior and the distinction between public holidays and observances, which goes beyond the schema's parameter descriptions.

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 explicitly states the tool computes deadlines or settlement dates by adding/subtracting business days, using a clear verb and resource. It distinguishes itself from siblings like count_business_days and is_business_day by focusing on date calculation rather than counting or checking.

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?

The description begins with 'USE THIS' to strongly indicate when to use, and provides context about computing deadlines instead of manual counting. However, it does not explicitly state when not to use or mention alternatives.

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

count_business_daysA

USE THIS to count working days between two dates instead of estimating — LLMs routinely miscount because they forget holidays or a country's weekend rule. Counts business days from start to end (both endpoints included by default), excluding that country's weekends and public holidays. Returns the count plus a breakdown of weekend days and the named holidays in range.

ParametersJSON Schema
NameRequiredDescriptionDefault
startYesStart date, YYYY-MM-DD.
endYesEnd date, YYYY-MM-DD.
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.
inclusiveNoInclude both endpoints (default true); false excludes the start date.
extraHolidaysNoOptional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day.

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description fully bears the burden of disclosing behavior. It states that both endpoints are included by default (hinting at the inclusive parameter), that weekends and public holidays of the specified country are excluded, and that the output includes a count plus a breakdown of weekend days and named holidays. This is sufficient for a counting tool, though it doesn't specify error handling or rate limits.

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

Conciseness5/5

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

The description is concise, consisting of two sentences with no wasted words. It front-loads the key instruction 'USE THIS', making it immediately clear. Every sentence adds value: the first explains why the tool is needed, and the second explains what it does and returns.

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?

The tool has 5 parameters, all described in the schema. There is no output schema, but the description mentions the return value (count plus breakdown). Given the complexity of a date-counting tool, the description provides enough context for an agent to understand input, behavior, and output. It could be more complete by noting edge cases like invalid dates, but it's adequate.

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 each parameter is already described in the schema. The description adds minimal additional meaning: it mentions the default inclusive behavior of both endpoints, which aligns with the inclusive parameter. This slight addition justifies a score slightly above baseline (3), as the schema does the heavy lifting.

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?

Clearly states the tool counts working days between two dates, accounting for holidays and weekends of a specific country. The description uses a specific verb 'count' and resource 'business days', and the name itself distinguishes it from sibling tools like add_business_days, is_business_day, etc.

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?

The description explicitly instructs to use this tool for counting working days instead of estimating, noting that LLMs commonly miscount due to holidays or weekend rules. It implies the tool is accurate but does not explicitly mention when not to use it or contrast with siblings beyond the name. Still, it provides clear context for its primary use case.

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

country_ruleA

USE THIS to see how bizdays treats a country before relying on a result — it returns the weekend days (with their source: a Qiniso override, CLDR, or the Sat/Sun default), whether a public-holiday calendar is applied, a confidence flag (verified vs unverified), and any caveats. Call this when a country looks unusual (Gulf states, Israel, Nepal) or when a result is surprising.

ParametersJSON Schema
NameRequiredDescriptionDefault
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description fully shoulders the burden. It discloses all key outputs (weekend day sources, calendar application, confidence, caveats) and implies read-only behavior. Missing are potential errors or auth requirements, but for a simple lookup, this is sufficient.

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

Conciseness5/5

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

Two sentences: first lists what it returns, second gives usage advice. Front-loaded with 'USE THIS', no redundant words. Highly efficient and well-structured.

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 tool's simplicity (1 param, no output schema), the description is comprehensive. It covers what the tool does, what it returns, and when to use it. No gaps for an agent to make a correct decision.

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% with a clear description for the 'country' parameter (ISO 3166-1 alpha-2, examples). The description adds no additional parameter semantics beyond usage examples, so baseline 3 is appropriate.

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 clearly states that the tool inspects how bizdays treats a country, listing specific outputs (weekend days, sources, public holiday calendar, confidence flag, caveats). This distinguishes it from sibling tools that modify or calculate business days, so an agent can easily differentiate.

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

Usage Guidelines5/5

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

Explicitly instructs to use this tool 'before relying on a result' and when a country is unusual (Gulf states, Israel, Nepal) or results are surprising. This provides clear when-to-use and implies when not to use, making it highly actionable.

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

is_business_dayA

USE THIS to check whether a specific date is a working day before scheduling on it — do not assume any weekday is open. Returns whether the date is a business day in the given country and, if not, the precise reason (weekend, public holiday with its name, or a custom holiday). Country-correct weekends and public-holidays-only.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYesDate, YYYY-MM-DD.
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.
extraHolidaysNoOptional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day.

TDQS

A4.3/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It states it returns whether it's a business day and the precise reason if not (weekend, public holiday, custom holiday). It mentions 'Country-correct weekends and public-holidays-only' which explains logic. No destructive or extra behaviors need disclosure.

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

Conciseness5/5

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

Two sentences are concise and front-loaded with 'USE THIS'. Every sentence adds value without redundancy.

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?

No output schema exists, but description hints at return value (business day status and reason). Also explains country-specific weekends and holidays. It is complete for a simple check tool with 100% parameter coverage.

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% so the schema already describes all parameters with types, descriptions, and requirements. The description adds no additional meaning beyond 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 clearly states the tool checks if a date is a working day before scheduling, and specifies it returns business day status with reasons. This distinguishes it from siblings like add_business_days or next_business_day which manipulate 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?

The description explicitly says 'USE THIS to check whether a specific date is a working day before scheduling on it — do not assume any weekday is open.' This gives clear when-to-use guidance. Alternatives are implied by sibling names but not explicitly listed.

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

next_business_dayA

USE THIS to find the next working day after a date (e.g. when something falls due on a weekend or holiday) instead of guessing. Returns the first business day strictly after the given date for that country.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYesDate, YYYY-MM-DD.
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.
extraHolidaysNoOptional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day.

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description bears full burden. It discloses that the result is the first business day strictly after the given date, taking into account the country and optional extra holidays. It does not mention error cases or performance, but provides sufficient behavioral context.

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

Conciseness5/5

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

The description consists of two concise sentences. The first sentence is an imperative directive, and the second explains the output. Every sentence adds value with no wasted words.

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?

Given no output schema, the description adequately explains the return value (first business day strictly after). It covers the parameters indirectly. It could mention error handling or edge cases, but for a simple tool, the completeness is satisfactory.

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%, so baseline is 3. The description reinforces the purpose but adds no new semantic detail beyond the schema, such as clarifying the 'extraHolidays' parameter or specifying date format beyond what is already in 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 clearly states what the tool does: find the next working day after a date, using a specific verb and resource. It distinguishes from siblings by emphasizing 'strictly after' and providing an example scenario, differentiating it from previous_business_day and add_business_days.

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?

The description includes an implicit usage guideline ('USE THIS... instead of guessing') and an example scenario, but it does not explicitly exclude alternatives or contrast with sibling tools. More explicit guidance would be beneficial.

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

previous_business_dayA

USE THIS to find the most recent working day before a date (e.g. the last open day before a holiday) instead of guessing. Returns the first business day strictly before the given date for that country.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYesDate, YYYY-MM-DD.
countryYesISO 3166-1 alpha-2 country code, e.g. US, GB, AE, SA, ZA.
extraHolidaysNoOptional extra non-working dates (YYYY-MM-DD), e.g. a company shutdown day.

TDQS

A4.3/5.0
Behavior4/5

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

Without annotations, the description carries full burden. It clearly states the return value ('first business day strictly before the given date for that country') and notes the effect of extraHolidays. However, it does not disclose any read-only nature or potential rate limits, which is acceptable for a simple lookup.

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

Conciseness5/5

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

Two sentences, front-loaded with 'USE THIS', zero waste. Every word is necessary and contributes to understanding.

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 no output schema, the description sufficiently explains what the tool returns. All parameters are described in schema, and the description covers the core behavior. For a simple utility tool, it is complete.

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 baseline is 3. The description adds meaning to 'extraHolidays' by providing an example ('e.g. a company shutdown day'). It does not add much to 'date' or 'country' beyond the schema, but the overall desc adds value.

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?

Description uses a specific verb-resource pair ('find the most recent working day') and distinguishes from siblings like 'next_business_day' by focusing on the 'previous' direction. The phrase 'USE THIS to find... instead of guessing' clarifies its unique role.

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?

The description implies when to use (before a date/holiday) and provides an alternative ('instead of guessing'), but it does not explicitly exclude other tools like 'next_business_day' or 'is_business_day'. For a straightforward tool, this is adequate but not explicit.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observedadd_business_days
    • First observedcount_business_days
    • First observedcountry_rule
    • First observedis_business_day
    • First observednext_business_day
    • First observedprevious_business_day

TDQS

A4.4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: adding/subtracting days, counting between dates, checking holiday rules, verifying a single date, and finding next/previous business days. No overlap exists.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_business_days, is_business_day, next_business_day). 'country_rule' is the only slight deviation but still fits the overall style.

Tool Count5/5

With 6 tools, the server covers all essential business day operations without unnecessary tools. The count is well-scoped for its purpose.

Completeness5/5

The tool set provides complete CRUD-like operations for business days: addition, subtraction, counting, checking, and finding adjacent days. The inclusion of country_rule adds transparency. No obvious gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Public holiday data for 30+ countries. Check holidays, working days, and full calendars via AI assistants like Claude and Cursor.
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    MCP server for business-day arithmetic with country-aware holiday calendars. It offers tools to check, calculate, and list business days and holidays for over 60 countries.
    9
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    The deterministic fact-verification layer for AI agents. Validates the structured facts an agent emits — IBANs, payment cards, VAT and national tax IDs, crypto and bank addresses, domains, emails, phone numbers, securities and academic identifiers, plus dates, currencies and holidays — against checksums and curated authoritative data, not guesses.
    56
    1
    Apache 2.0
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables Japanese business calendar operations such as holiday checking, business day calculations, payment date calculation, fiscal year determination, and deadline tracking, all locally without external API.
    MIT