U.S. federal holidays with observed dates and business-day math. Example from an open-source kit.
Scored across 5 tools
Each tool targets a distinct operation on the business-day/holiday domain: add (shift a date), check (is a date a business day), count (span between two dates), list (holidays for a year), and next (upcoming holidays). The verbs make the boundaries unambiguous, so misselection is unlikely.
All five tools use a consistent snake_case verb_noun pattern: add_business_days, check_business_day, count_business_days, list_federal_holidays, next_federal_holidays. The only variance is singular/plural nouns, which is semantically driven, not a convention break.
Five tools is a tight, well-scoped set for a holiday/business-day calculator, with no redundant or filler operations. Each tool covers a genuinely distinct computation the domain needs.
The surface covers the core lifecycle: shifting dates, validating a date, counting spans, enumerating a year's holidays, and looking ahead. A minor gap is the absence of a range-based holiday query spanning multiple years, but next_federal_holidays and list_federal_holidays make this workable.
Move a number of U.S. business days forward or backward from a date, skipping weekends and observed federal holidays, for due dates, delivery windows and notice periods. The start date is not counted: 1 business day after a Friday is the next Monday, or Tuesday when that Monday is a holiday. Returns the resulting date and every holiday it skipped. Up to 1,000 business days either way.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | The date to count from. It is not counted itself, written YYYY-MM-DD (for example 2026-11-26). Covers 2021 through 2100. | |
| business_days | Yes | Business days to move, -1000 to 1000. Negative counts backward. 0 returns the start date if it is a business day, otherwise the next one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly=true, idempotent=true, destructive=false), and the description adds genuinely new behavioral detail: the start date is not counted, negative values count backward, 0 returns the start date or the next business day, and the range is capped at 1,000 days. It also discloses the return content ('the resulting date and every holiday it skipped'), which matters since there is no output schema.
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 sentences, each carrying distinct information: scope/use cases, counting convention with edge-case example, and output/limits. Nothing is repeated from the name or title, and the core behavior is front-loaded.
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 two-parameter date-arithmetic tool with no output schema, the description supplies everything an agent needs: counting semantics, direction, limits, holiday handling, and the return shape. No meaningful gaps remain.
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 coverage is 100%, so the baseline is 3, but the description adds real semantic value: it clarifies the off-by-one convention with a worked example ('1 business day after a Friday is the next Monday, or Tuesday when that Monday is a holiday') and restates the ±1,000 bound. The negative-direction and zero-case behavior is meaningfully reinforced beyond the schema text.
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 ('Move a number of U.S. business days forward or backward from a date') and pins down the scope with 'skipping weekends and observed federal holidays'. This clearly separates it from count_business_days and check_business_day, which measure rather than shift a date.
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?
Names concrete use cases ('due dates, delivery windows and notice periods'), which tells the agent when this tool is appropriate. It stops short of explicit when-not guidance or naming a sibling alternative, so it is clear context rather than full routing.
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 U.S. business day (a weekday that is not an observed federal holiday). Returns the weekday, the holiday observed that day if any, and the business days just before and just after it.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date to check, written YYYY-MM-DD (for example 2026-11-26). Covers 2021 through 2100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes further by enumerating the return contents: weekday, any observed holiday, and adjacent business days. It does not cover invalid-date or out-of-range handling, but the added return disclosure is real value beyond structured fields.
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 sentences, both earning their place: the first defines the predicate and the second front-loads the payload the caller receives. No filler or restatement of the title.
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 no output schema, the description correctly compensates by listing what is returned, and annotations plus a fully documented single parameter cover the rest. Only edge-case behavior for invalid or unparseable dates is left unaddressed.
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% and there is only one parameter, so the schema already documents the YYYY-MM-DD format and the 2021-2100 range. The description adds no syntax or format detail beyond that, making the baseline 3 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 precise verb+resource ('check whether a date is a U.S. business day') and defines the term inline as 'a weekday that is not an observed federal holiday,' which is exactly what separates this from siblings like count_business_days or list_federal_holidays.
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 singular 'check whether a date' implies this is the single-date lookup tool versus the counting/arithmetic siblings, but the description never names an alternative or states when not to use it. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count the U.S. business days between two dates, both dates included, leaving out weekends and observed federal holidays. Returns the business day count, the weekend days, and each holiday that fell in the span. Spans up to 3,660 calendar days.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | Last date of the span, counted if it is a business day, written YYYY-MM-DD (for example 2026-11-26). Covers 2021 through 2100. | |
| start_date | Yes | First date of the span, counted if it is a business day, written YYYY-MM-DD (for example 2026-11-26). Covers 2021 through 2100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real context beyond them: what the result includes (count, weekend days, each holiday in the span) and a hard span limit of 3,660 calendar days, which is not present in the annotations or schema.
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 sentences, zero filler, front-loaded with the core action and scope before the return contents and limit. Every clause carries information an agent needs.
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 no output schema, the description helpfully enumerates the return contents, and the 2021–2100 date coverage lives in the schema parameter descriptions. Minor gap: it does not say what happens for out-of-range dates or spans over 3,660 days (error vs. clamp).
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 coverage is 100%, so the baseline is 3; the description earns above baseline by clarifying inclusive boundary behavior ('both dates included') and imposing the 3,660-day span constraint, which the schema does not state. It does not add format detail beyond the schema's YYYY-MM-DD examples.
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 (count) and resource (U.S. business days), plus the exact span semantics ('both dates included, leaving out weekends and observed federal holidays'). This is clearly distinguishable from siblings like check_business_day (single date) and add_business_days (offset from a date).
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 by the counting semantics: an agent can infer this is for measuring the number of working days across a span. However, no sibling is named and no when-not condition is given (e.g., use check_business_day for a single date, add_business_days for shifting a date).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the eleven U.S. federal holidays for one calendar year (2021 through 2100): each holiday's name, its actual date and weekday, the date it is observed when it falls on a weekend (Saturday moves to the Friday before, Sunday to the Monday after), and the rule that sets it, from 5 U.S.C. 6103. Use it to answer which days federal offices close in a year.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | Calendar year, 2021 through 2100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, closed-world, non-destructive behavior, so the bar is lower. The description adds genuine substance beyond them: the weekend-observance shift rule (Saturday to Friday, Sunday to Monday) and the statutory basis in 5 U.S.C. 6103, which clarify what the results mean.
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 sentences, front-loaded with the resource and scope, then the return contents, then the usage cue. The density is justified because no output schema exists to carry the field-level detail.
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 no output schema, the description fully enumerates the returned fields (name, actual date and weekday, observed date, governing rule), and annotations cover the safety profile. An agent has everything needed to call it correctly and interpret results.
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 coverage is 100% and the single `year` parameter is fully documented in the schema with the same 2021-2100 range. The description repeats rather than extends that information, so the baseline of 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 verb and resource (list U.S. federal holidays) with an exact scope: eleven holidays, one calendar year, 2021-2100. The scope and content detail clearly separate it from siblings like next_federal_holidays and check_business_day.
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?
"Use it to answer which days federal offices close in a year" gives a clear intended context for invocation. It stops short of naming alternatives or exclusions, so the agent must infer when next_federal_holidays would be preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the next one to eleven U.S. federal holidays observed on or after a date, with each one's observed date and how many calendar days away it is. Without from_date it starts from today's date in America/New_York and says which date it used.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many upcoming holidays to return, 1 to 11. Defaults to 1. | |
| from_date | No | Start looking on this date, inclusive, written YYYY-MM-DD (for example 2026-11-26). Covers 2021 through 2100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description adds real context beyond that: the implicit timezone (America/New_York) when from_date is omitted, the inclusive start boundary, and the fact the default date is echoed back in the response.
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 sentences, no filler, and the core capability is front-loaded ahead of the default-behavior caveat. Every clause carries information an agent needs.
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 no output schema, the description carries the return-value burden and does so: each holiday's observed date and the number of calendar days away. Combined with the timezone and inclusive-boundary notes, an agent has everything needed to call and interpret this correctly.
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 coverage is 100%, so both parameters are already documented, including the 1–11 count range and the YYYY-MM-DD format. The description largely restates those bounds; the only marginal addition is the documented default of 1 and the fallback timezone behavior, which the schema does not state.
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 ('find') and resource ('next ... U.S. federal holidays') plus the exact scope rule: observed on or after a date, up to eleven results. This cleanly separates it from the sibling list_federal_holidays, which enumerates rather than picking the upcoming ones from a start date.
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 explains the default path ('Without from_date it starts from today's date in America/New_York and says which date it used'), which tells the agent the no-arg case works. It never names an alternative sibling or states when not to use this tool, so usage is implied rather than directed.
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_dayscheck_business_daycount_business_dayslist_federal_holidaysnext_federal_holidaysUS federal holidays, business-day maths, invoice due dates and IRS deadlines.
Exact U.S. federal holidays and business days 1971-2100, OPM and Federal Reserve observance.
Deterministic date arithmetic with auditable receipts: business days, due dates, holidays.
NYSE, Federal Reserve, TARGET2 and UK business days, holidays and T+N settlement dates.
Add one secure layer between your agents and this server.
