List the upcoming public holidays for a country. Returns the next public holidays (from today onward) for the given country. Returns: Array of upcoming public holidays..
| Name | Required | Description | Default |
|---|---|---|---|
| countryCode | Yes | ISO 3166-1 alpha-2 country code, e.g. US, DE, CN. |
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.
Add one secure layer between your agents and this server.
The two tools are clearly distinct: one returns upcoming holidays from today, the other returns all holidays for a specific year. There is no overlap or ambiguity in their purposes.
Both tools follow a consistent 'get_' + descriptive noun pattern, and the names clearly reflect their functionality: 'get_next_public_holidays' and 'get_public_holidays'. The convention is uniform.
With only 2 tools, the server feels thin for a public holidays domain. While the core operations are present, the low count is borderline and may leave users wanting additional functionality such as listing supported countries.
The two tools cover 'next holidays' and 'holidays for a year', but there is no way to list supported countries or query holidays by specific date ranges. This is a notable gap that could cause agent failures when trying to validate country codes or find a holiday on a particular date.