tilwhen date engine

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe, deterministic operation. The description adds the key behavioral nuance 'exclusive counting' (start date is day 0), which is not in annotations. No contradictions.

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?

Single sentence that is front-loaded and precise. Every word serves a purpose with no redundancy. Ideal conciseness.

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 has an output schema (return values covered), good annotations, and is a simple arithmetic operation, the description is virtually complete. The only minor gap is not mentioning edge cases like leap years or timezone effects beyond default UTC.

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 67% (tz and date described, days not). The description adds meaning for the 'days' parameter by specifying 'N whole calendar days' and 'exclusive counting', but does not fully compensate for the missing schema description. 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 adds N whole calendar days to a date with exclusive counting (start date is day 0). This specific verb-resource combination distinguishes it from sibling tools like 'days_between' or 'business_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 description implies usage for simple day arithmetic via 'exclusive counting' but does not explicitly state when to use this tool vs alternatives like 'business_days' or 'next_occurrence'. No usage exclusions or context are provided.

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 indicate read-only, idempotent, non-destructive behavior. The description adds critical details: span mode exclusivity/inclusivity, timezone resolution of 'today', and optional holiday/workweek parameters. No contradictions.

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 compact sentences: first describes span mode, second add mode plus optional features. No wasted words, information front-loaded.

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 8 parameters, 88% schema coverage, existing output schema, and optional parameters, the description covers both operational modes and optional configurations. Could explicitly link parameters to modes, but implied sufficiently.

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 covers 88% of parameters with descriptions; the description groups parameters into modes and explains their roles (span vs add), adding context beyond schema defaults. However, some syntactical details (e.g., ISO date format) are already in 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 two computation modes (span and add) with specific verbs and resources. It distinguishes from sibling tools by specifying business-day logic with holidays and custom workweeks.

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?

No explicit when-to-use guidance or comparative advice against siblings. The description implies use for date calculations involving business days and holidays, but does not exclude simpler alternatives like 'add_days' or 'days_between'.

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, idempotentHint, and destructiveHint. The description adds key behavioral details: signed result, midnight-to-midnight computation, endpoint exclusivity, and that it returns a gap. No contradictions.

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?

A single sentence packs all essential information: what the tool computes, the unit (whole calendar days), the time boundary (midnight to midnight), and endpoint treatment (exclusive). No redundant phrasing.

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 output schema exists, the description does not need to detail return values. It explains the calculation method comprehensively. For a simple date difference tool, no additional context is necessary.

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 provides descriptions for all three parameters (from, to, tz). The description adds contextual meaning about how dates are interpreted (midnight-to-midnight, exclusive endpoints), but does not elaborate on parameter syntax beyond the schema. With high schema coverage, the description offers modest additional value.

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 computes 'signed whole calendar days from one date to another, midnight to midnight, endpoints exclusive'. It uniquely identifies the tool's function and distinguishes it from siblings like business_days and add_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 description provides clear context on what the tool computes, allowing the agent to infer when to use it vs. siblings. It does not explicitly state exclusions or alternatives, but the specificity of 'whole calendar days' and 'endpoints exclusive' guides appropriate use.

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 read-only and idempotent behavior. The description adds value by disclosing the output includes a receipt and derivation steps, which is not captured by 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 consists of two sentences that directly convey the core functionality. It is front-loaded with the main action and contains no superfluous content.

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 high parameter count and existence of output schema, the description adequately covers the tool's purpose. It states it runs any operation and returns explanation, which is sufficient for the agent to understand when to invoke this tool.

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 53%. The description adds the key insight that parameters are discriminated by op, but does not elaborate on individual parameters. The schema provides adequate descriptions for most, so the description provides moderate additive value.

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 runs any operation and returns a receipt plus derivation steps. It distinguishes from siblings by noting it accepts the same fields discriminated by op, making the purpose specific and unique.

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 usage when explanation is needed by stating it returns human-readable derivation steps. It mentions accepting same fields as other tools, but does not explicitly state when not to use or list alternatives, though the sibling list is provided.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds transparency about output details (nominal date, status, warning for declared-only holidays), which supplements the annotations 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?

The description is a single sentence that efficiently conveys the tool's purpose and key behavioral details. No unnecessary words, and it is front-loaded with essential information.

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 low complexity, comprehensive annotations, and presence of an output schema, the description provides sufficient context about the tool's behavior and output, though it could briefly mention the output schema's existence.

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% (both parameters have descriptions in the JSON Schema). The tool description does not add new parameter semantics beyond the schema, meeting the baseline for complete schema coverage.

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 title 'Public holidays for a jurisdiction and year' and description clearly state the tool returns observed public holidays with nominal date and status. It distinguishes from sibling date calculation tools by focusing on holiday data retrieval.

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 usage for getting public holidays but does not provide explicit guidance on when to use this tool versus alternatives or mention any prerequisites or exclusions.

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 indicate read-only, idempotent, non-destructive. The description adds valuable behavior: calendar days counting, roll-forward over weekends and holidays with jurisdiction/custom calendar. No contradictions.

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 wasted words. Front-loaded with core purpose, then key options. Every sentence adds 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?

Given the output schema exists, no need to detail returns. Description covers core logic and optional features. Could mention an example but acceptable.

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 71%, so baseline 3 applies. The description adds context for the net parameter but does not elaborate on other parameters beyond what their schema 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 the tool calculates due dates for Net-N payment terms, with invoice date as day 0. It distinguishes from siblings like business_days or add_days by focusing on net terms and optional roll-forward.

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 usage for net payment terms but does not explicitly state when to use versus alternatives (e.g., add_days for simple date addition). No exclusions or conditions provided.

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, idempotentHint=true, destructiveHint=false. The description adds that the occurrence is 'strictly after' the base date and resolves today in the given timezone, but these are minor additions. No contradiction.

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 core purpose, no filler. Every sentence adds 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?

Given the presence of an output schema (not shown but mentioned), the description adequately explains inputs and constraints. It could mention timezone resolution more explicitly, but it's sufficient for a simple tool.

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 50% (tz, from have descriptions). The description clarifies 'event' (slug like 'christmas') and 'weekday' (0-6 range) which are missing from schema, and explains default for 'from' as today.

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 it finds the next occurrence of an event slug or weekday after a base date, with examples. It distinguishes from siblings like 'holidays' (which lists holidays in a year) and 'days_between' (difference).

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 'Provide exactly one of event/weekday', guiding parameter selection. However, it does not contrast with sibling tools or state when not to use this tool.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns an auditable receipt and handles ambiguous dates by returning needsClarification, providing useful behavioral context beyond 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 two concise sentences. The first sentence clearly states the primary function, and the second adds a critical detail about ambiguity. No redundant information.

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 presence of an output schema, the description sufficiently covers input format, answer behavior, and ambiguity handling. The term 'normalized operation' could be clarified, but the overall completeness is high.

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 67% (2 of 3 params have descriptions). The description provides an example for the 'q' parameter (e.g., '90 business days from today in uganda'), adding context not in the schema. However, it does not elaborate on 'tz' or 'locale' further than the schema already does.

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 parses natural-language date queries, normalizes them, answers the question, and returns an auditable receipt. It also mentions handling ambiguous dates, which distinguishes it from sibling tools that focus on specific date 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 implies use for natural-language date parsing but does not explicitly state when to use this tool over siblings or when not to use it. No alternatives or exclusions are mentioned.

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 idempotentHint=true, so the safety profile is clear. Description adds 'whole calendar days' but omits edge cases (e.g., DST transitions, invalid dates).

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?

Single concise sentence with no wasted words. Could be slightly more structured but remains effective.

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 available, the description need not detail return values. However, it omits behavior for edge cases (negative days, zero days, large N) and does not specify that the result is a date string.

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 67%, but description does not elaborate on any parameter. The 'days' parameter lacks a schema description and is not explained in the tool 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?

Description clearly states the tool computes a date N whole calendar days before a given date. It distinguishes from siblings like add_days and business_days through the phrase 'whole calendar days', implying no business day logic.

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?

No guidance on when to use this tool over alternatives like business_days or days_between. Description does not mention that it handles simple calendar day subtraction, not business days.

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