UAE Calendar Oracle

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the lower bar applies. The description still adds genuine behavioral detail: data_confidence semantics, estimated_items, sources, data_version, and the flag that private-sector weekends are employer-set. Good value 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?

Front-loaded with the core operation, then use cases, then an example, then return shape. Every sentence carries information, though the example and return-field enumeration make it longer than strictly necessary.

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 an output schema exists, the description needn't restate return values but does so usefully for the confidence/estimation semantics. Combined with a fully covered input schema, an agent has everything needed to call it correctly; the only omission is sibling routing against compute_deadline/working_days_between.

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 documents every parameter including the negative-days semantics. The description reinforces negative counting and supplies a worked example using start_date/days/emirate/sector, but adds little syntax or meaning beyond the schema. 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?

States a specific operation (compute a date N working days after/before a start date) with the key qualifiers (UAE emirate/sector, weekend and public-holiday skipping). An agent can distinguish it from siblings like is_working_day or list_holidays. It does not explicitly distinguish it from compute_deadline or working_days_between, which is the only clarity gap.

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?

Gives concrete use contexts (SLAs, delivery promises, HR processing times, 'within X business days' wording). No explicit exclusion or routing versus the closest siblings (compute_deadline, working_days_between), so it stops short of full when/when-not guidance.

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 rich behavioral detail beyond annotations: return fields (raw date, skipped days, step-by-step explanation), a disclaimer field, data_confidence semantics, estimated_items, sources, and a worked example. It also clarifies that estimated holidays are flagged. Annotations (readOnly, idempotent, non-destructive) are consistent with this.

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 front-loaded with the core action, followed by usage context, scope caveat, and a compact example. Every sentence carries information; there is no filler or redundancy despite the paragraph length.

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 tool with six parameters (including nested rules), three enums, and an output schema, the description covers the essential behavioral traits: what is returned, how confidence is signaled, and the UAE-specific context. It also repeats the output schema fields so the agent can set expectations without opening the schema.

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 baseline is 3. The description adds meaningful context by listing the counting-rule categories ('exclude start day, extend past weekends/holidays, half-day handling, estimated-holiday handling') and a concrete example showing how parameters interact with output. It doesn't explain every parameter's syntax, but it meaningfully augments 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 a specific verb ('Compute') and resource ('deadline') and immediately distinguishes scope: 'date arithmetic only; it does not state what any law requires.' It also names the units and counting rules, making clear how this differs from simpler sibling tools like add_working_days or working_days_between.

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 provides clear context for use ('Use when drafting contract, notice, appeal or payment deadlines in the UAE') and explains the meaning of rule defaults. However, it does not explicitly name alternative tools or state when NOT to use this tool, which keeps it from a 5.

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 establish readOnly, idempotent, non-destructive behavior, and the description adds important domain-specific caveats: the result is computed, may differ by ±1 day, and has medium data_confidence. It also explains confidence levels and mentions estimated_items and official sources, which is valuable context beyond the 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 front-loaded with the conversion purpose and remains reasonably efficient. It does enumerate response fields despite having an output schema, which is slightly redundant, but the confidence-level explanation 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?

Given the single required parameter, full schema coverage, annotations, and an output schema, the description covers what an agent needs: the computed nature, confidence semantics, intended uses, and an example. No critical behavioral or contextual information appears missing.

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%, and the schema already documents the single date parameter with ISO format and valid range. The description provides an example input but does not add semantic constraints beyond what the schema already states, so 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?

States a specific verb and resource: convert a Gregorian date to the Hijri calendar using Umm al-Qura tables. The direction is unambiguous and clearly distinguishes it from the inverse sibling hijri_to_gregorian.

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?

Gives clear positive guidance: use for Hijri-dated documents and to estimate Islamic holidays. It also warns that the official UAE date is set by moon sighting and may differ, implying it should not be treated as authoritative for official dates, but it does not name a specific alternative tool or source.

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 a safe, idempotent read operation, and the description adds important behavioral limitations beyond them: the result is computed, may be ±1 day versus the moon-sighted UAE date, and always reports data_confidence, estimated_items, sources, and data_version. It also explains the semantics of 'high' versus 'medium' confidence.

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 front-loaded with the conversion direction, range, and method, then immediately adds the key caveat and response metadata. Every sentence contributes useful information without unnecessary padding.

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 already present, the description does not need to enumerate return fields, but it still highlights the most important response metadata and the ±1 day accuracy caveat. Combined with the annotations, it provides everything an agent needs to call the tool correctly and interpret its output.

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 only parameter is already well documented. The description repeats the format and range and adds a useful example, but does not provide meaningfully deeper semantics beyond what the schema already states.

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 and resource ('Convert a Hijri date ... to Gregorian'), including the supported range and method. It clearly distinguishes this tool from its inverse sibling gregorian_to_hijri by naming the conversion direction explicitly.

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 to use this tool by naming the input calendar and date range. It does not explicitly mention alternatives such as gregorian_to_hijri, but the conversion direction makes the intended use unambiguous.

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?

Beyond the read-only annotations, the description discloses important behavior: reasons include weekend, named public holiday with status, or Friday half day; Islamic holidays may be estimated or confirmed; and responses include data_confidence, estimated_items, sources, and data_version. It also gives a concrete example showing sector-dependent results.

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 purpose and usage context are front-loaded, followed by the critical moon-sighting caveat and a compact example. Despite covering several nuances, no sentence is wasted and the structure supports quick agent scanning.

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 complexity, rich schema, annotations, and output schema, the description is complete enough for correct invocation. It explains the core result reasons, confidence semantics, estimated-item handling, and sector/emirate sensitivity without redundantly restating the full schema.

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 baseline is 3. The description adds value with an example showing how date, emirate, and sector affect the result, but it does not discuss apply_optional_overlays, so it does not fully compensate or add complete parameter semantics 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 opens with a specific verb and resource: telling whether a date is a UAE working day for a given emirate and sector, and explaining why not. It clearly distinguishes this from calendar-listing or range-computing siblings by framing the tool as a single-date working-day check with reasons.

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 gives clear usage context: call before scheduling, promising delivery, booking, or filing anything on a UAE date. It does not explicitly state when not to use it or name alternatives such as working_days_between or next_holiday, so it falls short of a full 5.

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, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond the schema by explaining status values (estimated | announced | confirmed | moved, with original dates preserved) and how to interpret data_confidence ('high' = all announced/confirmed, 'medium' = something estimated). It does not cover caching or data freshness limits beyond 'last-checked time'.

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?

Front-loaded with what it returns and scoped by, then usage, then a concrete example. It is somewhat dense — the first sentence packs names, dates, status, source URL and last-checked time — but almost every clause carries information an agent would otherwise have to infer.

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?

An output schema exists, so enumerating return fields is optional, yet the description usefully highlights confidence semantics and the estimated_items/sources/data_version envelope. Minor gap: it says 'list all' without noting the include_estimated filter default, which slightly understates its own behavior.

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% with rich per-parameter descriptions and enums, so the schema carries the load. The description's example ({year:2026, emirate:'federal', sector:'private'}) adds a little illustration but no new semantics, and include_estimated is never mentioned in the 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?

States a specific verb (list) and resource (public holidays) plus the exact scoping axes: Gregorian year, emirate, sector. It is clearly distinguishable from siblings like next_holiday and working_days_between, which answer point/deadline questions rather than enumerating a year.

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?

Gives concrete use cases (annual planning, HR calendars, showing provisional dates) that tell the agent when this is the right tool. It stops short of naming alternatives or exclusions — e.g. 'for the next upcoming holiday use next_holiday' is absent, and nothing says when not to use it.

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, idempotent, closed-world behavior, and the description adds materially new context: the data_confidence vocabulary, estimated_items[], official source URLs, and data_version. That is exactly the kind of behavioral detail annotations cannot convey.

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?

Front-loads the answer (what it returns) in the first clause, then usage, then example, then response contract. Dense but every sentence carries information; the parenthetical confidence glossary is justified because agents need it to interpret results.

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 an output schema existing, the description still surfaces the fields that change how an agent phrases its answer (confidence level, estimates, version). Combined with rich annotations and fully documented params, nothing needed for correct invocation or interpretation is missing.

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% and the enum fields are well documented, so the baseline is 3; the description goes further by demonstrating a realistic from_date/emirate/sector combination and what each implies in the output. It doesn't restate the default semantics of emirate='federal', hence a 4 rather than 5.

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?

States a specific verb and resource ('Return the next public holiday on or after a date'), names the scoping dimensions (emirate/sector) and enumerates the returned fields. The 'next' framing cleanly separates it from list_holidays in the sibling set.

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?

Explicitly says when to use it ('when is the next long weekend / holiday' questions, warning about upcoming closures) and supplies a worked example call with a concrete result. It doesn't name an alternative sibling or state exclusions, which keeps it short of a 5.

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, idempotent, closed-world, so safety is covered. The description adds genuinely new behavior: it returns 'not_announced' rather than guessing when no rule is published, and it explains data_confidence semantics and the presence of estimated_items/sources. It repeats some return-shape info that the output schema already carries, keeping it from a 5.

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?

Front-loaded with purpose, then fallback behavior, then usage, then an example — a sensible order with no filler sentences. It is dense and long-ish, and the return-field enumeration is partly redundant with the output schema.

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 three parameters with two enums, full schema coverage, and an existing output schema, the description covers everything an agent needs: purpose, fallback semantics, confidence model, and an example call.

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 baseline is 3. The description goes beyond the schema by giving a worked example ({year:2026, emirate:'federal', sector:'public'}) that ties parameter combinations to expected output, and by framing dates as 'observed or estimated'.

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?

States a specific verb+resource: returns Ramadan start/end for a Gregorian year AND the officially published reduced working-hour rules per emirate/sector. This clearly separates it from siblings like working_hours (general hours) and list_holidays (holiday enumeration).

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?

"Use for scheduling during Ramadan and for HR policy questions" gives clear usage context. It does not explicitly name alternatives or exclusions (e.g. 'use working_hours for non-Ramadan queries'), so it stops short of full routing guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by explaining the data_confidence levels ('high' = officially announced, 'medium' = estimated) and the presence of estimated_items, sources and data_version. It also flags the half-day counting behavior. It stops short of describing weekend/weekday handling for private sector beyond what the schema says, so not a full 5.

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?

Front-loaded with the core operation and the output shape, with the example placed mid-text where it supports comprehension. The final sentence enumerating response metadata is slightly list-heavy but each element (confidence, sources, version) carries real decision value, so little is wasted.

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 present, the description needn't re-document return values, yet it usefully clarifies confidence semantics and half-day behavior. Combined with 100% schema coverage, an agent has everything needed to call this correctly; only edge behavior for private-sector weekend assumptions is left to the schema.

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% — the emirate, sector, inclusive and date parameters are all documented with defaults and semantics in the schema itself. The description's 'choose which endpoints to include' and the example reuse that information rather than adding syntax or format detail, so 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?

States a specific verb and resource ('count working days between two dates') with explicit scope ('for a UAE emirate/sector') and what it returns (Friday half days, non-working day list). This is clearly separable from siblings like add_working_days or is_working_day, which operate on offsets or single dates.

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?

Names concrete use cases (leave calculations, payroll, project durations, lateness) and a worked example with parameters, which gives a strong sense of when to reach for it. However, it never explicitly excludes alternatives — e.g., it doesn't say to use is_working_day for a single date or add_working_days for offsets, so routing between siblings still requires 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?

Goes well beyond the readOnly/idempotent annotations by disclosing that private-sector weekends are employer-specific and only a flagged default is applied, plus the confidence model (high vs medium), estimated_items, sources and data_version. These are the exact caveats an agent needs before trusting the answer.

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?

Front-loads the core question, then usage, then an example, then response caveats – good ordering. It spends a sentence enumerating response fields (data_confidence, estimated_items, sources, data_version) that an output schema already covers, which is mild 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?

For a 3-parameter lookup with full schema coverage and an output schema, everything an agent needs is present: scope, defaults, timezone handling for naive datetimes, and the reliability semantics of the answer. Nothing material is missing.

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% and the schema already explains sector and emirate enums, so the baseline would be 3. The description adds real value with a worked example showing a full parameter combination and the resulting shape, plus the reminder that 'federal' is the safe default.

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?

Names a specific decision (does a datetime fall inside working hours for an emirate/sector) and enumerates the inputs that affect the answer (weekends, holidays, Friday half day, Ramadan hours). This clearly distinguishes it from date-level siblings like is_working_day and add_working_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?

Provides explicit usage situations: 'Use before calling a government office, scheduling a meeting or promising same-day action.' It does not, however, explicitly route to or exclude the closest siblings (is_working_day, working_days_between), leaving that comparison to inference.

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