timezone-toolkit

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

With no annotations present, the description carries the full burden of behavioral disclosure, and it does this well by explaining key nuances: days are calendar-based and DST-safe while hours and minutes are absolute, and diff supports datetimes in different zones. It does not describe the return format or edge-case behavior, but the stated semantics go meaningfully beyond the 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?

The entire description is one well-structured sentence with no filler. The primary purpose is front-loaded, and the parenthetical packs important behavioral nuance without bloating the text. Every phrase contributes to understanding how the tool behaves.

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 schema covers parameters thoroughly, and the description adds important behavior semantics, but there is no output schema and the description does not disclose what the result looks like (e.g., a formatted datetime string or a duration object). For a tool with conditional nested parameters and no annotations, this is a notable gap, though the core behavior is clear.

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 baseline is 3. The description adds value by clarifying the semantic meaning of units—DST-safe days versus absolute hours/minutes—and by noting that diff can operate across different timezones. This complements rather than repeats 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 identifies the tool as timezone-aware date arithmetic with two specific operations: add/subtract a duration and compute a difference between datetimes. This is more specific than the bare name 'calculate' and distinguishes it from most siblings, though it does not explicitly name a sibling like 'offset' to contrast with.

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 explains what the tool does rather than when to prefer it over alternatives. There is no explicit 'use this when' guidance or comparison with sibling tools such as 'now', 'offset', or 'timezones'. The timezone-aware framing implies a relevant use case, but the agent is left to infer selection criteria.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It transparently states accepted input types (ISO 8601, natural language), batch capability, and the exact return fields (converted datetime, UTC offset, zone abbreviation, DST flag). This goes beyond a bare functional statement, though it does not cover edge cases like invalid timezone names or DST transition ambiguities.

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 compact: two sentences front-load the core action, then list accepted input formats and return fields. Every phrase earns its place, with no filler or redundancy.

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 moderate complexity, the lack of annotations, and the absence of an output schema, the description covers the essentials: input formats, timezone type, batch mode, and output components. It is complete enough for an agent to make a first correct call, though the 'batch' feature is underspecified and would benefit from clarification.

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?

The input schema has 100% parameter coverage, so the baseline is 3. The description adds little beyond the schema: it reiterates the datetime format and introduces 'batch', which is not reflected in the schema's single datetime string and could even cause slight ambiguity. It does not deepen understanding of the from/to parameter semantics beyond what the descriptions already provide.

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 ('Convert') and resource (date/time between IANA timezones), and immediately distinguishes it from sibling conversion tools like convert_units and currency_convert by emphasizing timezone conversion. The mention of 'single or batch' further clarifies its scope.

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 the tool's use case—timezone conversion—but provides no explicit guidance on when to prefer it over alternatives like offset, timezones, or convert_units. It does not name alternatives or exclusion criteria, leaving the agent to infer the appropriate selection context from the description alone.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the conditional behavior (returns the holiday name if the date is a holiday) and notes that the data comes from an authoritative public-holiday dataset, but it does not describe edge cases such as invalid country codes, date format errors, or the exact non-holiday return value.

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 two concise sentences with no filler. The core action is front-loaded, and the dataset credibility note adds useful context without bloating the text.

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 lookup tool with only two well-documented parameters and no output schema, the description is nearly complete: it defines the input semantics, the condition, and the expected result. It could be slightly more explicit about what happens when the date is not a holiday, but the conditional phrasing already implies no name is returned.

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 date and country_code already described in the input schema. The tool description reinforces that country_code is an ISO 3166-1 alpha-2 code but adds no additional semantic detail beyond what the schema already 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?

The description clearly states the tool's action: checking whether a given date is a public holiday in a country and returning the holiday name if so. It identifies the resource (public holiday by country code) and uses specific verbs that distinguish it from the sibling tools, none of which target this function.

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 conveys a clear use case: when you need to know if a date is a public holiday in a specific country. However, it does not explicitly state when not to use it or mention any alternatives, so the usage guidance is mainly implied rather than 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?

With no annotations provided, the description carries the full behavioral burden. It discloses weekend exclusion, public-holiday exclusion behavior, the free-tier limit of at most one slot, and that the paid endpoint returns every matching slot via an 'upgrade' signal in the response. It does not mention auth requirements, rate limits, or the exact slot format, but it covers the most decision-relevant behaviors well.

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 dense sentences with no filler. The main action and key constraints are front-loaded, and the free-tier/paid-endpoint distinction is placed efficiently at the end. Every clause earns its place.

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 has nested parameters and no output schema, so the description needs to provide meaningful context. It explains the core algorithm, exclusions, and plan-dependent response behavior. It does not describe the exact shape of returned slots or provide an example, but the schema provides strong parameter examples and the description gives enough for effective invocation.

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 all three parameters. The description adds useful semantic context by explaining that participants' timezones are the basis for overlap, duration determines meeting length, and country affects holiday exclusions. This goes beyond simply restating parameter names.

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 states a specific verb ('Find'), a clear resource ('working-hour time slots'), and precise scoping conditions: overlapping availability across timezones, meeting duration, weekends excluded, and holidays excluded when relevant. It is clearly distinguishable from all sibling tools, none of which perform meeting-slot scheduling.

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 gives clear context for when the tool should be used: finding mutually available meeting times across participants in different timezones. It does not name specific alternatives or exclusions, but no sibling tool is a plausible alternative, so the lack of explicit when-not guidance is not a significant gap.

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?

With no annotations provided, the description carries the full disclosure burden. It states that the operation is a read of the current local time and lists the exact data components returned, leaving little ambiguity about side effects or 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?

Two sentences with no filler: the action and output components are front-loaded, and the usage condition is appended second. Every word contributes 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?

The tool is simple (one required parameter, no output schema), and the description explains both the return payload and the use case. An agent has sufficient information to invoke it correctly, with edge cases like invalid timezones implied by the schema's IANA constraint.

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 timezone parameter with examples. The description merely reiterates 'IANA timezone' and adds no new meaning beyond what the schema provides.

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 uses a specific verb ('Get') and resource ('current local time in an IANA timezone'), and enumerates the returned components (UTC offset, zone abbreviation, DST state). This clearly distinguishes it from siblings like 'timezones' (listing zones) and 'offset' (likely offset calculations).

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 explicitly states when to use the tool: 'whenever you need to know what time it is now somewhere.' It does not mention exclusions or list alternatives, but the usage condition is clear enough for an agent to select it 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?

With no annotations provided, the description carries the full behavioral burden. It discloses DST-awareness, correct handling of fractional offsets (e.g., India +05:30, Nepal +05:45), and the notion of 'exact' offset. It does not mention the return format or error behavior for invalid timezones, but for a pure calculation tool this is sufficient disclosure.

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 tight sentences with no filler. The core action is front-loaded, and the fractional offset examples earn their place by clarifying edge-case behavior.

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 two-parameter, read-only calculation tool with a fully documented schema, the description covers the essential semantics: timezone, instant, DST behavior, and fractional offsets. Minor omissions like the exact return format and invalid-input behavior are not fatal given the tool's simplicity.

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 both parameters including instant's format and default and timezone's IANA type. The description adds behavioral context (DST-aware, fractional offsets) but no new parameter-level meaning 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 uses a specific verb ('Get') and a precise resource ('exact UTC offset of an IANA timezone at a given instant'), and further distinguishes the tool by highlighting DST-awareness and fractional offsets. This makes it clearly differentiated from sibling tools like timezones, now, and convert without needing to open their schemas.

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: to compute an offset for a specific timezone at a specific instant. However, it does not explicitly state when not to use it or name alternatives such as timezones or convert, leaving some routing decisions 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explains that the tool can search by city/region/country and resolve names to timezone(s), which goes beyond a simple action statement. It does not detail edge cases like empty-query behavior, but for a read-only lookup this is adequate.

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 two sentences with no filler. The primary function is front-loaded, and the usage guidance earns its place by explaining why an agent would call this tool.

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 single-optional-parameter lookup tool, the description covers the core operation, search dimensions, and the intended purpose in the larger tool ecosystem. It does not detail the exact response shape, but the absence of an output schema and the simple nature of the result make the description reasonably complete.

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?

The schema already documents 'query' as a case-insensitive substring filter with 100% coverage, so the baseline is 3. The description adds value by clarifying that the query applies to city/region/country and that resolution to timezone(s) is supported, enriching the otherwise generic filter description.

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's function: listing/searching valid IANA timezone identifiers and resolving city/country names to timezone(s). It uses specific verbs and identifies the resource, making the tool's purpose easy to understand. It does not explicitly contrast with siblings like 'now' or 'offset', so it falls short of 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?

The description explicitly says to use this tool to discover the exact timezone identifier to pass to other tools, which provides clear usage context. It does not mention when to avoid it or name alternative tools, but for a lookup tool the guidance is sufficient.

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