Public Holidays

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the behavioral detail that holidays are returned 'from today onward' and that the return type is an array. However, it does not disclose edge cases like empty results, timezone handling, or holiday structure beyond that.

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 short but redundant: 'List the upcoming public holidays for a country' and 'Returns the next public holidays (from today onward)' essentially repeat the same information. The trailing 'Returns: Array of upcoming public holidays..' adds a return type note but includes a double period. It is not as tight as it could be.

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 the tool's simplicity (one parameter, no output schema, read-only annotation), the description covers the basic behavior and return type. However, it lacks details about the structure of each holiday object, potential empty arrays, or any additional constraints. The sibling tool comparison is also absent, so completeness is adequate but not thorough.

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 countryCode as an ISO 3166-1 alpha-2 code with a pattern. The description merely refers to 'given country' and adds no additional semantic information beyond what the schema provides. 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?

The description clearly states the tool 'List the upcoming public holidays for a country' and further specifies 'Returns the next public holidays (from today onward)'. This is a specific verb+resource with a temporal scope that distinguishes it from the sibling tool 'get_public_holidays' by emphasizing 'next' and 'from today onward'.

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 implies when to use the tool (for upcoming holidays from today onward) but does not explicitly mention when to use the alternative 'get_public_holidays'. There is no 'when not to use' or exclusion guidance, leaving the comparison to inference.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context that results include local and English names, date, and scope, and that the return is an array. No contradictions with 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 description is short and front-loaded with the main purpose. However, it contains a slight redundancy: 'Returns every public holiday...' is repeated in 'Returns: Array of public holidays...' with a double period, which is a minor structural flaw.

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 simple list tool with rich annotations and a complete schema, the description adequately explains the return content (local/English names, date, scope). It could explicitly mention the sibling tool for better contextual completeness, but the core information is present.

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%, with both parameters (year and countryCode) well described in the schema. The description does not add parameter-level details, but the baseline of 3 is appropriate since the schema carries the full burden.

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 the tool lists public holidays for a given country and year, with the explicit scope of returning every holiday for that period. This distinguishes it from the sibling tool get_next_public_holidays, which likely returns only upcoming 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 implies when to use the tool: when you need all public holidays for a specific country and year. It does not explicitly exclude alternatives or mention the sibling tool, so it lacks the when-not-to-use guidance that would merit a 5.

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