US Federal Holidays and Business Days

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

Adds substantial behavior beyond the read-only/idempotent annotations: exact holiday observance, start date exclusion, zero-day edge case, and the fact that skipped holidays are listed in the result. These are the details an agent needs to predict output without an 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, front-loaded with the core operation, then edge cases. No wasted words and every sentence carries semantic value.

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?

Covers the operation, edge cases, and the fact that skipped holidays are listed, which is important because there is no output schema. It could be slightly more explicit about the exact return shape (e.g., date string plus holiday array), but it is otherwise complete for a computational calendar tool.

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 already 80% and documents calendar modes and extra closures well. The description adds meaning the schema lacks, notably the zero-day behavior and that the start date is not counted, though it does not further explain calendar or include_inauguration_day 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 ('Adds ... N business days to a date') and includes the sign convention for reverse movement. It is clearly distinguishable from siblings like count_business_days and is_business_day without needing to open 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?

Provides clear operational context: negative values subtract, zero behaves specially, and the result skips weekends and observed holidays. It does not explicitly route the agent away from alternatives such as count_business_days, so it lacks full when-not guidance.

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

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

Annotations already declare readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely non-schema behavior: the negative count when end precedes start, the supported date range, and that excluded weekday holidays are returned. It does not state error handling for out-of-range or malformed dates, keeping it just short of a 5.

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 tight sentences, each carrying distinct information: scope and range, inclusivity semantics, and the negative-count and return-content behavior. Nothing is repeated from the schema or wasted.

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 read-only tool with no output schema, the description covers the important edge cases an agent needs (inclusivity defaults, negative results, listed excluded holidays, date range). Sibling routing and calendar-selection guidance are the remaining gaps.

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 43%, so the description must compensate. It adds real meaning for include_start/include_end via the Excel NETWORKDAYS analogy, clarifying inclusive boundary counting beyond the mere default values. But calendar, extra_closed_dates, and include_inauguration_day are left entirely to the schema, and the date format is undocumented in prose.

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 (counts) and resource (business days) with useful scope limits: the 1971-2100 supported range and the two calendar variants. It implicitly contrasts with add_business_days by emphasizing counting between two dates, but never names the sibling tools, so differentiation relies on inference.

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?

Explains the counting convention (weekends and observed holidays excluded, NETWORKDAYS-style inclusivity), which tells the agent what this tool is for. It never says when to reach for is_business_day, add_business_days, or invoice_due_date instead, and the calendar-selection guidance lives in the schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: it specifies which holiday calendar is used ('exact observed federal or Federal Reserve holidays') and clarifies the month-boundary edge case in modified_following. It does not state the return format or how unknown/out-of-range dates are handled.

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?

A single dense sentence with the core computation front-loaded, followed by the optional rolling and holiday-source detail. Every clause carries information an agent needs; nothing is redundant with the title or 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?

With five parameters, two enums, and no output schema, the description covers the computation, the roll modes, and the holiday source well enough to call the tool correctly. The main gap is that it never describes the return value (presumably a date string) or confirms what happens when roll='none' and the date falls on a holiday.

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 80%, so the baseline is 3, but the description adds meaning the schema does not: it spells out the semantics of following, preceding, and modified_following in prose and reinforces that net_days is calendar days (Net 30 = 30). extra_closed_dates is left to the schema, and calendar is only partially discussed in the description, keeping it below 5.

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?

The description opens with a specific verb and resource ('Computes an invoice due date') and names the inputs (issue date, net terms) plus the optional rolling behavior. It is clearly distinct from generic siblings like add_business_days or is_business_day that operate on a date without invoice/net-terms semantics.

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 establishes the context of use (converting net terms to a due date, optionally rolling to a business day) and explains the three roll modes, which is genuine usage guidance. It stops short of explicitly excluding alternatives, e.g. it never says to use add_business_days directly when you already have a computed date rather than net terms.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety is covered. The description earns credit by disclosing the supported date window, the return contents, and the Saturday-observance divergence between calendars — real behavioral context beyond the annotations. It is silent on what happens for out-of-range dates, keeping it below a 5.

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 core behavior, followed by the one nuance an agent is most likely to get wrong. No filler.

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?

There is no output schema, and the description compensates by naming exactly what comes back (boolean result, holiday name, adjacent business days). The supported date range is stated. Edge behavior beyond 1971-2100 is unaddressed, which is the only material gap for a 4-parameter predicate tool.

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 75% and the enum parameter already documents both calendars including the Saturday/Sunday observance rules, so the baseline is 3. The description's calendar example largely restates that schema text, and it says nothing about extra_closed_dates or include_inauguration_day, so it adds no meaning beyond the structured fields.

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 ('Says whether a date ... is a business day'), scopes the supported range (1971-2100), and enumerates the returned facts (holiday name, previous and next business day). This clearly separates it from the arithmetic siblings add_business_days/count_business_days, which shift or count rather than test a single 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?

Gives concrete context for the calendar choice via the 2026-07-03 federal-vs-Fed example, which tells the agent when the two modes diverge. It never routes explicitly against siblings (add_business_days, count_business_days) or states exclusions, so it falls short of a 5.

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

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

Goes well beyond the annotations: explains observed-date shifting rules with a concrete example (New Year's Day 2022 observed 2021-12-31), notes Fed Banks stay open the Friday before a Saturday holiday, and discloses keyed rule history (Juneteenth 2021, MLK 1986, Veterans Day 1971-1977). Also states "No network calls," which the openWorldHint=false hint alone doesn't fully convey.

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?

Front-loads the core promise in the first clause and packs in real value, but the second sentence is heavily nested with parentheticals and rule lists, making it denser than it needs to be for reference use.

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 one-parameter lookup with no output schema, the description effectively anticipates the return shape by naming the three date kinds (legal, OPM observed, Fed closure) and the optional Inauguration Day flag. Nothing an agent needs in order to call it correctly is missing.

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?

Single required parameter with 100% schema coverage, so the schema already carries the range 1971-2100 with min/max. The description restates the range but adds no new syntactic or semantic detail about the year argument, 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 verb and resource ("Exact U.S. federal holidays") plus a hard scope (1971-2100) and the governing statute. This clearly separates it from the sibling tools, which all do business-day arithmetic rather than holiday lookup.

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 use case (get the holiday list for a given year) is implied clearly, but the description never explicitly contrasts itself with siblings like is_business_day or count_business_days, nor says when not to use it. Routing is left to inference.

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