Date Calculator

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), yet the description still adds real value: it declares that holiday-data failure is a hard error rather than a silent weekday-only result, and it discloses the computational bound of 10 API requests of up to 11 years each plus one retry. That error-semantics and rate/bound disclosure is exactly what an agent needs before committing to a large date range; only the return payload detail is thin, and an output schema exists.

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 core operation and its scoping defaults are front-loaded, and every later sentence carries distinct information: weekend configuration, error policy, return contents, and request bounds. Slightly dense and the final parenthetical about retries is awkwardly nested, but nothing is 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?

For an 8-parameter tool with an output schema, the description covers defaults, error behavior, and computational limits, and the schema covers parameter formats and enums. The only real gap is the absence of explicit routing guidance among the three sibling date/holiday 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 description coverage is 75%, so the baseline is 3. The description restates the defaults (no excluded weekdays, no holidays, later endpoint excluded) and gives one practical mapping ('[0,6] for weekends'), but that largely duplicates enum/pattern/default metadata already present in the schema and adds no guidance on the country/region dependency beyond what the schema states.

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 opening sentence names a specific verb and resource ('Count calendar or matching days between two Gregorian dates') and pins the semantics with a reference implementation. An agent can distinguish it from shift_date (which moves a date) and get_holidays (which lists them), though siblings are never named 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 implied through defaults and configuration hints ('Use excludeWeekdays [0,6] for weekends'), which tells the agent how to get a business-day count. However, there is no explicit when-to-use vs shift_date/get_holidays guidance and no statement of when this tool should not be chosen.

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 and non-destructive, so the safety bar is lower. Beyond that, the description adds genuinely non-obvious behavior: the at-most-11-inclusive-years cap (not encoded in the schema), native-language name fallback, coverage/language metadata, and a prompt-injection warning that returned names are data rather than instructions. It still says nothing about error behavior for unsupported codes 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.

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

Three front-loaded sentences: purpose first, then the constraints and discovery pointer, then the safety/fallback caveat. Each sentence carries distinct information and nothing is repeated from the schema 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 an output schema present, the description need not explain return values, and it wisely only notes the metadata signals (coverage and language). Combined with annotations this is enough to call the tool correctly. The only real gap is guidance on what happens when a country/region combination is unsupported.

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 60%: region, country and language are documented in the schema, but startYear and endYear have no descriptions at all. The description compensates by supplying the missing constraint on the year range ('at most 11 inclusive years'), which is the key undocumented semantic. The language parameter is not addressed in the description, leaving that gap to the schema alone.

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: 'Read public holidays including observed dates.' The holiday-calendar scope is unmistakably distinct from count_days, shift_date and list_locations, and it explicitly routes code discovery to the list_locations sibling. It stops short of a full sibling differentiation sentence, so a 4 rather than a 5.

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 conditions for a correct call: supply a country, an optional exact subdivision, and no more than 11 inclusive years, plus a pointer to list_locations for discovering supported codes. It does not state when NOT to use this tool or contrast it with shift_date/count_days, which keeps it out of 5 territory.

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 two real behavioral facts beyond them: the payload includes year coverage, and returned country/region names are untrusted data rather than instructions. It still says nothing about response size or whether all countries in one call is expensive.

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 what is returned, then how the optional parameter changes behavior. The trailing data-not-instructions clause is terse and earns its place, though it reads as a bolted-on safety note rather than integrated guidance.

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?

The tool is a single optional-parameter read with an output schema, so return values need no explanation here. The description covers what is returned, both call modes, and the trust level of the returned data — nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents the single country parameter as an uppercase ISO code. The description adds the omit-vs-supply semantics (omission means all countries; supplying returns subdivision codes), which is genuine meaning beyond the schema, but only for one parameter.

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 country codes, regions and year coverage') plus the source ('holiday API'). It is unmistakably the discovery/lookup tool among siblings count_days, get_holidays and shift_date, which all operate on dates rather than enumerating locations.

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 mode selection: omit country to get everything, or supply a country to get its exact subdivision codes. It does not name the sibling it should precede (e.g., use this to discover codes before calling get_holidays), so the routing guidance is clear but not fully explicit.

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 read-only, idempotent, non-destructive semantics, and the description adds substantive behavior: start excluded and destination included, month/year units converting to calendar-day span, the all-weekdays-excluded fallback surfaced in businessDaysRan, and the returned rules/provenance/share link. This is genuine context beyond structured fields, though the exact resolution order for combining years with exclusions is only gestured at.

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 dense but front-loaded, leading with the operation before the edge-case rules. A few clauses are jargon-heavy ('become their calendar-day span before matching-day adjustment', the businessDaysRan reference) but each sentence carries operational meaning.

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 11 parameters, exclusion logic, and an output schema already present, the description targets exactly the non-obvious parts: exclusion ordering, the start/destination boundary, and the degenerate all-excluded case. Remaining gaps (per-parameter meaning of region/country, error behavior for missing holiday data) are largely covered by schema descriptions.

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 45% across 11 parameters, so the description must carry weight. It clarifies the unit semantics (nonnegative whole years/months/weeks/days) and the exclusion boundary rule, which the bare schema does not, but it adds nothing about country/region/language/excludeHolidays beyond what schema descriptions already say and does not tie mode to the arithmetic outcome.

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-resource pair ('Add or subtract nonnegative whole years, months, weeks and days'), making the operation unmistakable. It does not explicitly contrast itself with count_days or get_holidays, so an agent must infer the boundary from the sibling names alone.

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: it is for shifting a date by units under specific exclusion rules. There is no explicit 'use this instead of count_days when...' guidance, nor any note about prerequisites such as needing country before excludeHolidays (that appears only in the schema).

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