Business-Day Oracle

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

Goes well beyond the annotations: it discloses that the weekend defaults to the country's legal weekend, that overriding the weekend changes the confidence grade, and the meaning of each confidence tier (fixed-date vs lunar/moon-sighted/projected). It also warns about estimated_items[], sources[], data_version and warnings[] in the response, which is real behavioral context an agent needs before trusting the output.

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-loaded with purpose and return shape, then usage, then calendar selection, then response details — a sensible order with no filler prose. It is on the long side and repeats some parameter facts the schema already documents (weekend override, categories, extra_holidays), costing a point.

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 an 11-parameter, calendar-dependent tool with an output schema, the description supplies everything needed: the semantics of the result, the confidence grading, projected-holiday handling, and where the calendars come from. Nothing material that an agent would need to call it correctly is left implicit.

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 100%, so the baseline is 3; the description earns above that by giving concrete value examples for country ('SA', 'DE', 'US'), market ('XNYS', 'XLON'), subdivision ('BY'), weekend (['FRI','SAT']) and extra_holidays (company/contract dates). It does not cover language, count_start_day or include_estimated_holidays, leaving those to the schema's own 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 N working days from a date, skipping weekends and holidays', and names the return ('the end date and every skipped day with its reason'). That scope is unmistakably distinct from working_days_between (counts between two dates) and roll_date (snaps to a working day), so an agent can select it 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?

Gives concrete usage contexts (delivery promises, SLA clocks, payment terms in business days) and a worked example with start_date/days/country/subdivision, plus explicit calendar-selection guidance (country OR market, optional subdivision from list_calendars). It stops short of naming when to prefer a sibling such as roll_date or working_days_between, but the context is clear enough to route correctly.

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 cover read-only/idempotent/non-destructive, and the description still adds substantive behavior: what the response contains (raw vs final deadline, skipped days, explanation trail, disclaimer), the data_confidence levels and what triggers medium confidence, estimated_items, sources and warnings. That is exactly the kind of context annotations cannot carry.

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-loaded with the purpose and the counting/rolling behavior, then calendar selection, then response shape; every block earns its place for a 14-parameter tool. It is dense and long-winded in places (the response sentence is a run-on), which keeps it from a 5.

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?

Given 14 parameters and an output schema, the description supplies the decision logic (which calendar source, how confidence is derived, what warnings mean) that structured fields do not. Slight redundancy in re-explaining return fields already covered by the output schema, and no negative guidance about sibling tools.

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 still adds cross-field meaning — country OR market selects the calendar, subdivision codes come from list_calendars, weekend defaults to the country's legal weekend, extra_holidays are company/contract dates — plus a worked example. It stops short of explaining exclude_start_day or month_end_clamp, which only the schema covers.

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?

Names a specific verb and resource ('Compute the end of a period ... from a start date') and enumerates the counting, rolling and explanation behaviors, so the operation is unambiguous. It never names a sibling (add_working_days, roll_date, working_days_between) to draw the boundary, so it falls short of full differentiation.

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?

'Pass the rules the contract/law states; defaults are the common ones' gives a context for use, and the calendar-selection sentence hints at inputs. But there is no explicit when/when-not guidance and no routing to roll_date or add_working_days, so the agent must infer which sibling to call.

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 establish this is a safe, idempotent, closed-world read; the description goes well beyond them by disclosing the confidence model (high = fixed-date calendar, medium = lunar/moon-sighted or caller-overridden weekend), the presence of estimated_items[], sources[], data_version and warnings[]. That is exactly the kind of uncertainty disclosure an agent needs before trusting the boolean result.

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 and example are front-loaded, and the dense semicolon-separated clauses each carry information (calendar selection, defaults, response contract). It is on the long side for a single-tool description, but nearly every clause earns its place; the packed formatting costs it a point rather than any real waste.

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?

Despite an output schema existing, the description still summarizes the response contract (result, data_confidence, estimated_items, sources, warnings) so an agent can decide how much to trust the answer. With 1 required parameter out of 9 and full schema coverage, nothing needed to call this 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?

Schema coverage is 100%, so the schema already documents each parameter; the description still adds meaning the schema lacks, notably that market means a trading/settlement calendar rather than a country, that overriding the weekend degrades data_confidence, and that extra_holidays covers company/contract dates. Only include_estimated_holidays is left to the schema alone, so this is above the baseline-3 case.

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 ('say whether a date is a working day') and adds the crucial 'why not' output framing (weekend, holiday name, observed, projected lunar). The country/subdivision-or-market scoping distinguishes it clearly from siblings like working_days_between or next_holiday, and a concrete example ('2027-03-10', 'SA') makes the call shape obvious.

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 explicit calendar-selection guidance (use country OR market, optional subdivision pulled from list_calendars) and explains what the weekend override and categories mean, which is real routing/parameterization context. It stops short of stating when to prefer a sibling such as list_holidays or next_holiday instead, so it is clear but not fully comparative.

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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that the tool is free and explains the meaning of data_confidence, estimated_items, sources, data_version, and warnings. This is unusually rich behavioral context that helps an agent interpret results and understand projection uncertainty.

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?

The description is front-loaded with the core behavior and the meaningful distinction between no-argument and country-specific calls. It is dense but largely earns its length; the final response enumeration is somewhat long given that an output schema exists, though the confidence semantics add real 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?

For a discovery tool with a simple one-parameter schema, full schema coverage, complete annotations, and an output schema, the description provides everything needed: what the tool returns, how to invoke both modes, and how to interpret confidence and warnings. Nothing critical 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?

Schema coverage is 100%, so the schema already documents the country parameter, including its role as country code or market MIC and the omit-to-list-all behavior. The description reinforces this with an example ('US') but does not add syntax or format details beyond what the schema provides, so the 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 ('Discover calendars') and precisely defines scope: no arguments returns all 250 countries and 30 markets, while a country code returns calendar metadata. This clearly distinguishes it from the date-computation siblings like compute_deadline and list_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 description clearly explains the two usage modes (omit country to list everything, provide country for details), which gives an agent enough to choose the right call pattern. It does not explicitly route the agent to sibling tools or state when to use this versus them, which keeps it from 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: the weekend defaults to the country's legal weekend, categories default to ['public'], and data_confidence explains how calendar reliability degrades (lunar/projected holidays or an overridden weekend). The response-field enumeration overlaps the output schema, which keeps this from 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?

Front-loaded: what it returns, then how to select a calendar, then response metadata. Dense and largely waste-free, though the trailing response enumeration partially restates what the output schema already documents.

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 9-parameter read tool with an output schema, everything an agent needs is present: selector semantics, defaults, the projection/confidence caveat, and sources/warnings signaling. Nothing required 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?

Schema coverage is 100%, so the baseline is 3. The description does add interpretive value for a few parameters — the include_estimated_holidays tradeoff (count projected dates as non-working vs. ignore until announced), the weekend override example, and extra_holidays as company/contract dates — but leaves language and the exact category vocabulary to 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?

Opening sentence states a specific verb and resource ('All holidays of a year') plus the exact scoping dimensions (country/subdivision/categories or market). This clearly separates it from siblings like next_holiday (single upcoming date) or working_days_between (counting), which an agent can distinguish without opening any 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?

It explains the two mutually exclusive calendar selectors (country vs market MIC) and routes the agent to list_calendars for valid subdivision codes, plus a concrete worked example ('year 2027, country IN, subdivision KA'). It lacks explicit 'use X instead when...' exclusions against siblings such as next_holiday, 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?

Beyond the read-only, idempotent annotations, the description explains projection behavior, data_confidence levels, estimated_items, sources, data_version, and warnings. This gives the agent meaningful behavioral context about how uncertainty is surfaced 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?

The description is front-loaded with the core purpose and then supplies useful invocation and response details. It is somewhat dense, but most sentences carry relevant information and there is no major waste.

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 10-parameter tool with a full input schema, output schema, and safety annotations, the description provides enough context to call it correctly and interpret projection-related output. No critical completeness gap remains.

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 the parameter schemas already document country, market, weekend, categories, subdivision, extra_holidays, and include_estimated_holidays thoroughly. The description repeats much of that and adds an example, but does not substantially extend parameter semantics 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?

The description clearly states a specific verb and resource: returning the next N holidays on or after a date, including supporting fields like days_until and projection flags. It is distinguishable from siblings such as list_holidays or is_working_day, though it does not explicitly name those alternatives.

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 example invocation and calendar-selection notes make the intended usage reasonably implied, but the description never explicitly says when to choose this tool over list_holidays, list_calendars, or other siblings. It provides invocation context rather than selection 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?

Beyond the readOnly/idempotent hints, the definition discloses real behavior: weekend defaults to the country's legal weekend, data_confidence meaning (high for fixed-date calendars, medium for lunar or overridden weekends), estimated_items naming projected dates, sources, data_version and warnings. That is a lot of operational context an agent cannot get from the annotations.

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?

The opening sentence is front-loaded with the verb, the convention list, and the primary use cases, so value comes first. The remainder is one very dense run-on paragraph covering calendar selection and response shape; it is efficient but slightly overstuffed for a single block.

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 10-parameter, single-required-input tool, the definition covers calendar selection paths (country vs market), subdivision, categories, weekend override, extra holidays, and the confidence semantics, so nothing needed to call it correctly is missing. An output schema exists, yet the brief confidence explanation still adds useful interpretation guidance.

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?

With 100% schema coverage the baseline is 3, and the description genuinely adds meaning on top: it explains ISDA semantics for modified_following, points to list_calendars for subdivision codes, and links include_estimated_holidays to the data_confidence flag. Minor duplication of MIC/ISO examples with the schema keeps it from a 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 definition names the exact operation (apply a business-day convention to a date) and the four conventions in parentheses, and it frames the scope with concrete domains (payment, coupon, settlement, SLA dates) plus a worked example. It is unmistakable against is_working_day or add_working_days because it describes shifting a date rather than counting or testing days.

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 concrete use cases (payment dates, coupon dates, settlement, SLA due dates) and the 'country or market, optionally subdivided' selection rule give clear context for when the tool applies. However, it never names when to prefer it over siblings such as add_working_days, compute_deadline, or is_working_day, so the agent must infer the boundaries.

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 carry readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the default weekend rule, the data_confidence high/medium semantics tied to lunar or overridden weekends, and the presence of estimated_items, sources, data_version and warnings. This is substantive behavioral context; it stops short of stating rate limits or what happens for invalid/unknown country codes.

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?

The opening sentence is front-loaded and useful, but the third sentence 'Leave cost, lateness, elapsed business days' is a malformed fragment that adds noise and ambiguity, and the description then becomes a dense run-on of parameter and response detail. Several clauses duplicate schema content that could be trimmed.

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 an 11-parameter calendar tool with an output schema and full annotations, the description covers calendar selection, weekend defaults, confidence semantics and returned fields. The only real gap is that the confusing 'Leave cost, lateness...' clause leaves it unclear whether certain cost/lateness concepts are deliberately out of scope.

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, market, weekend, categories, subdivision, extra_holidays and include_estimated_holidays are already fully documented in the schema. The description largely restates those with an example ('AE', inclusive 'both'), adding modest value such as pointing to list_calendars for subdivision codes — 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 ('Count working days between two dates') with scope qualifier 'with endpoint control' and notes it also lists the non-working days. It is distinguishable from siblings like add_working_days and is_working_day by implication, but it never names them or contrasts the operation explicitly.

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 only implied: calendar selection guidance (country OR market, plus optional subdivision/categories) tells the agent how to pick a calendar, but there is no explicit statement of when to use this versus compute_deadline or roll_date. The garbled fragment 'Leave cost, lateness, elapsed business days' reads like an attempted exclusion list but is too broken to function as guidance.

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