tilwhen date engine

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

Annotations already indicate read-only and idempotent behavior. The description adds that counting is exclusive (start date is day 0), but lacks details on timezone handling, error cases, or range limits (provided in 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?

Single sentence is concise but slightly terse. It is front-loaded but could be expanded slightly for clarity without becoming verbose.

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?

Despite having an output schema, the description lacks important context such as how timezone affects the result, default behavior for 'today', and edge cases. For a date math tool, it feels incomplete.

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?

Description adds no information beyond the input schema. Parameters like 'tz' and 'date' are only documented in the schema; the description does not clarify their usage or defaults beyond what's in 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 states the tool computes a date offset by N calendar days with exclusive counting. It distinguishes from siblings like 'subtract_days' and '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?

No explicit guidance on when to use this tool versus siblings such as 'business_days' or 'next_occurrence'. The description only details the counting method.

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?

The description adds significant behavioral context beyond the annotations: exclusive start day, inclusive end day for span mode; resolution of 'today' in timezone; working week options; and holiday customization. Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description supplements with operational details.

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 packed with information, front-loaded with the key distinguishing feature (span vs add modes). Every phrase earns its place, with no redundancy or 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?

Given the complexity (two modes, 8 parameters, optional holidays), the description covers the essential behavior for both modes and mentions all configurable options. With an output schema present, return values need not be explained. It is sufficient for an agent to understand when and how to use 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 description coverage is 88%, so many parameters are already explained. The description adds value by explaining how parameters relate to modes (from+to for span, days+date for add). However, it does not detail the interaction between jurisdiction and customHolidays or the default workweek, leaving some semantics implicit.

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 modes (span and add) with specific verbs ('business days between', 'the date N business days away'). It distinguishes itself from siblings like 'days_between' and 'add_days' by focusing on business day calculations with holiday and working week options.

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 scenarios via the two modes but does not explicitly contrast with siblings. For example, it does not state 'use days_between for calendar days' or 'use this for workday calculations'. While the context is clear, explicit when-not-to-use guidance is missing.

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?

The description adds behavioral details beyond annotations: 'signed', 'midnight to midnight', 'endpoints exclusive'. Annotations already indicate read-only, idempotent, non-destructive; description enriches with exact calculation semantics. 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?

Single sentence, no redundancy, every word adds value. Front-loaded with key action and semantics.

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 annotation coverage (readOnly, idempotent, non-destructive) and output schema (present), the description fully explains behavior. No gaps remain.

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 descriptions cover 67% of parameters (from, tz; to is referenced). The tool description does not add parameter-level meaning beyond the schema, so baseline 3 applies. No extra semantics needed given 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 description clearly states the tool computes signed whole calendar days between two dates, specifying 'midnight to midnight, endpoints exclusive (the gap)'. This uniquely identifies its purpose and distinguishes it from sibling tools like business_days or 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 implies usage for calculating date differences, but does not explicitly state when to use this tool over alternatives. The context from sibling tools (e.g., business_days for business day counts) provides implicit guidance, but lacks explicit 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 already declare readOnly, idempotent, and non-destructive. Description adds 'returns receipt plus steps' but no further behavioral details beyond what annotations imply.

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 concise sentences with no redundant content. Front-loaded with the core action and key differentiator.

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?

Despite having an output schema, the description lacks detail about what 'receipt' or 'derivation steps' entail, and does not cover the complexity of 15 parameters 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 coverage is only 53%, but the description defers to 'same fields as other tools' without explaining any parameter specifics or adding 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 clearly states the tool runs any operation and returns a receipt plus derivation steps, distinguishing it from siblings that return only results.

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?

It explains the tool accepts the same fields as other tools discriminated by 'op', implying usage when explanation is needed. No explicit when-not or alternatives, but context is clear.

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?

Description informs that declared-only holidays are omitted when the year is undeclared, with a warning. This goes beyond the annotations (readOnlyHint, idempotentHint) to disclose data completeness behavior. 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, front-loaded with the tool's purpose, efficiently adding a critical behavioral note about incomplete data. No unnecessary words.

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 simple nature (2 required params, output schema exists, annotations rich), the description covers the key behavioral aspect (incomplete data warning) and overall purpose. No additional information is needed for correct 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 has 2 parameters with 50% description coverage (jurisdiction has aliases, year has none). The tool description does not add further semantics to either parameter beyond what is in the schema. The description's mention of 'jurisdiction and year' is minimal.

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?

Title and description clearly state that the tool retrieves observed public holidays for a given jurisdiction and year, specifying what information is returned (nominal date and status). This distinguishes it from sibling tools which are date arithmetic functions.

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 context indicates this is a holiday lookup tool, distinct from date calculation siblings. No explicit when-to-use or when-not-to-use guidance is provided, but the purpose is clear enough for an agent to select 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?

Annotations already indicate idempotent and read-only behavior. The description adds value by explaining calendar day counting, day-0 basis, and optional roll-forward past weekends/holidays, complementing the annotations without 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?

The description is two sentences, front-loading the core purpose and then adding optional features. It is concise without unnecessary detail, though slightly more structure could improve readability.

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 many parameters and constraints like mutual exclusivity of jurisdiction and customHolidays, the description covers the main use case but lacks detail on parameter interactions and edge cases. Output schema exists, so return values need not be described.

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% with descriptions for most parameters. The description clarifies 'net' as number of calendar days and 'roll' as roll-forward, but does not fully detail all parameter interactions (e.g., workweek defaults). 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 calculates due dates for Net-N payment terms, specifying that invoice date is day 0 and offering optional roll-forward. This distinct purpose separates it from siblings like add_days 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 net terms with holiday adjustments but does not explicitly state when to use this tool versus alternatives like add_days or business_days. No 'when not to use' guidance 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 indicate readOnly, idempotent, non-destructive. The description adds behavior: 'strictly after' and 'default today'. 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 conveying all essential information with no fluff. Front-loaded with purpose and constraints.

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 indicated), the description focuses on input semantics and usage constraints, which covers the tool's purpose adequately.

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 50% but the description adds meaning for event and weekday (example for event, range for weekday). The schema covers tz and from, so description complements well.

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 finds the next occurrence of a tracked event slug or weekday strictly after a base date. It distinguishes from sibling tools like add_days or business_days which are about date arithmetic or filtering.

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 requires providing exactly one of event or weekday, and explains the default base date. It does not mention when not to use the tool or compare to siblings like holidays, but the context is sufficient.

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, destructiveHint. Description adds value by disclosing that ambiguous dates return needsClarification and that output includes an auditable receipt. 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, front-loaded with purpose and behavior. Every sentence adds distinct value. No unnecessary words.

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 output schema exists (not shown but noted), description covers both normal outcome and the needsClarification edge case. Parameters are sufficiently contextualized. Complete for a parsing tool with 3 parameters.

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 adds context: example queries for 'q', explains 'tz' as IANA timezone defining 'today', and clarifies that omitting 'locale' triggers clarification choices for ambiguous dates. This adds 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?

Description clearly states the tool parses natural-language date queries like '90 business days from today in uganda' into a normalized operation, answers it, and returns an auditable receipt. It distinguishes itself from sibling tools by handling broad queries rather than specific date arithmetic.

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?

Provides example queries and explains behavior for ambiguous dates (needsClarification). Does not explicitly state when to prefer this tool over siblings, but the sibling list implies specific arithmetic tools, so usage context is clear.

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. Description adds that it uses calendar days and resolves 'today' in a timezone, but does not disclose that negative values effectively add days, which is a key behavioral nuance.

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 contains zero unnecessary words. Highly concise.

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 date manipulation tool with an output schema, the description provides core behavior. Missing mention of return format, but overall sufficient.

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% (tz and date described, but days only has min/max). The description mentions 'N whole calendar days' but does not explain negative values or constraints 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 states the tool calculates a date N whole calendar days before a given date. It clearly distinguishes from siblings like add_days, but could be more explicit about subtraction.

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 versus alternatives like business_days or days_between. The description does not specify prerequisites or exclusions.

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