Date Math

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds genuinely new context: a per-call price of $0.001 via x402, DST awareness, and the fact that country holidays are honored. It does not cover failure modes, such as what happens when both hours and end are supplied, or whether the 1-year window is an error.

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, both dense with signal: the computational scope first, then the pricing constraint. No filler or restatement of the title.

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 return values need not be explained, and the cost note plus DST/holiday coverage handle the main complexity for a 10-parameter tool. The remaining gap is the mutual exclusivity of the two modes and how hours versus minutes combine, which an agent must deduce.

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?

With schema coverage at 50%, the description carries part of the load: it names business hours, custom hours, workdays, holidays and country public holidays, which maps to hours, work_start/work_end, workdays, holidays and country. However, minutes is never mentioned in the description and its relationship to hours is left ambiguous, and defaults (work_start 09:00, work_end 17:00, start = now) are only inferable from 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 precise domain and two concrete operations: the deadline N business hours after a start time, or business time elapsed between two times. That distinguishes it cleanly from calendar-based siblings such as date_add and from the overlap-oriented working_hours_overlap, without needing to open the schema.

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 its usage through the two modes and the holiday/workday configuration, but it never states when to prefer it over date_add, date_diff, or working_hours_overlap, nor does it warn about the interaction of hours with a country code. The explicit mode selection ('pass hours/minutes' vs 'end') lives only in the schema description, not here.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: a per-call cost of $0.001 via x402 and the 7,000+ city coverage, both of which affect whether an agent should batch calls. It stops short of describing error behavior for unknown or ambiguous cities.

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 dense sentence with the core capability front-loaded, followed by examples, scale, and cost. 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?

An output schema exists, so return values need not be explained, and the cost and coverage details round out the picture. The main gap is the absence of guidance on ambiguous-name resolution and on how 'at' interacts with the returned local time.

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%, and the description clarifies that cities are passed by name and that country disambiguates common names like Springfield, which adds real meaning beyond the schema. It says nothing about the 'at' parameter or the city-vs-cities exclusivity, leaving half the parameters to the schema alone.

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 ('Find the IANA time zone and current local time') plus scope ('up to 10 cities by name') and coverage ('7,000+ cities'). It does not explicitly distinguish itself from siblings like timezone_convert or public_holidays, so an agent must infer that this is a name-based lookup rather than a conversion.

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 parenthetical '"Springfield" + country' implies when the country parameter is needed for ambiguous names, and 'up to 10 cities' signals batching. However, there is no explicit when-to-use versus timezone_convert or public_holidays, and no statement of what happens when a name is ambiguous and country is omitted.

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 openWorldHint, so the safety profile is covered. The description adds a genuinely useful behavioral fact, the $0.001 per-call x402 cost, which is not in the schema or annotations. It does not explain how payment is handled or whether calls require pre-authorization, so it is adequate rather than rich.

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 short sentences with the core capability front-loaded and the cost note appended. Nothing is redundant and every sentence carries 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?

An output schema exists, so return-value explanation is unnecessary, and the parameter schema is fully described. The description covers purpose, time-zone scope and pricing. The only gap is that the x402 payment flow is not explained, which could matter for an agent deciding whether the call will succeed.

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 expression, from, count and timezone are all documented structurally. The description mentions time zone handling but adds no syntax, format or constraint details beyond the schema, making the baseline 3 correct.

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: explain a cron expression and list its next run times. That is concrete and distinguishable from siblings like date_add or timezone_convert. It doesn't explicitly name an alternative, so it falls short of 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 phrase 'in any time zone' implies context for use, but there is no explicit when-to-use or when-not-to-use guidance and no named alternatives among the many date/time siblings. Usage is implied rather than stated.

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 only declare readOnly/idempotent/closed-world, yet the description adds genuinely new behavior: month-end clamping semantics and the fact that business days skip weekends, supplied holidays, and country public holidays. It also discloses cost ($0.001 per call via x402), which no structured field conveys. It stops short of covering ordering of applied units or timezone/DST effects on hour arithmetic.

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 terse, front-loaded sentences with the unit list first, then the behavioral caveats and cost. Every clause carries information; nothing is redundant 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?

For an 11-parameter tool with an output schema present, the definition covers the important edge cases an agent needs: clamping, holiday exclusion, and cost. Minor omissions are unit application order and timezone handling for sub-day units, which affect correctness in mixed-unit calls.

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 only 36%, so the description must compensate, and it largely does by enumerating all eight unit parameters plus the holiday and country modifiers in prose. The remaining gap is that interaction rules (e.g., ordering when multiple units are supplied) live mainly in the schema-level description rather than here.

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 (add or subtract) and resource (date) and enumerates every supported unit, from years down to seconds and business days. This clearly separates it from siblings like date_diff, which measures rather than shifts 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?

Usage context is implied through the unit list and the note that business days skip weekends and holidays, which hints at when to prefer business_days over days. However, it never says when to use this instead of siblings such as business_hours_deadline or recurring_dates, and gives no prerequisites for the datetime requirement beyond what the schema states.

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 read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuinely useful non-schema context: the $0.001 per-call x402 cost, plus the half-open interval and weekend/holiday exclusion semantics for business days. It does not contradict any annotation, though it says nothing about error behavior for invalid or reversed date ranges.

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?

One front-loaded sentence covering result modes, followed by the interval semantics and the cost. The nested parenthetical about business days is dense and slightly hard to parse, but every clause carries information an agent needs.

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 need not explain return values, and annotations plus full schema coverage handle the safety and parameter burden. The remaining relevant additions, pricing and counting semantics, are present; only comparative usage guidance against the many date siblings 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%, so all four parameters are documented at the source, making 3 the baseline. The description adds marginal value by reiterating the 'pass country to exclude its public holidays' behavior, but that semantics is already present in the country and holidays property descriptions, so little is added 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?

Opens with a specific verb+resource ('Difference between two dates or datetimes') and enumerates the result modes (calendar Y/M/D, total days/weeks/hours, business days), which makes it clearly distinct from the additive sibling date_add. It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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 the business-day counting rule and that passing country excludes public holidays, which gives some guidance on parameter choice. It never states when to use this tool versus date_add, business_hours_deadline, or working_hours_overlap, and there are no exclusions or prerequisites.

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 state readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuine non-annotation context: a per-call price of $0.001 and the x402 payment mechanism, which materially affects invocation decisions. It does not mention any rate limits or failure behavior for invalid dates, keeping it below 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?

A single sentence that front-loads the resource and enumerates outputs compactly, with the cost note appended. Nothing is redundant and nothing is buried.

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 the description does not need to explain return values; the cost model is disclosed. What remains unaddressed is edge behavior, such as how invalid or out-of-range dates are handled, which matters slightly for a computation tool that takes a strict-pattern input.

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?

There is one parameter with 0% description coverage, so the description should compensate but only says 'for a date'. The schema itself carries a regex pattern and a concrete example (2026-11-07), so the expected format is still discoverable structurally. The description adds no timezone, range, or validation semantics beyond that.

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 the resource (calendar facts for a date) and enumerates exactly which facts it derives: weekday, ISO week, quarter, day of year, leap year, weekend. That enumeration distinguishes it from siblings like date_diff or date_add without needing to name them. No explicit sibling comparison is made, so it stops 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?

Usage is only implied: an agent can infer it should call this when it needs derived calendar attributes for a single date. There is no explicit when-not guidance and no routing to alternatives such as parse_date_text (for turning text into a date) or date_add/date_diff (for arithmetic).

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 openWorldHint=false, so the safety profile is covered; the description goes further by disclosing a per-call price of $0.001 via x402, which is operationally important and appears nowhere in the structured fields. It also notes the relativity to a reference time and zone, which explains why results depend on when the call is made. Output details are left to the output 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?

Two sentences, front-loaded with the core verb and example inputs; the pricing note is appended as a distinct practical caveat. Nothing is repeated from the schema or annotations, and no sentence 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?

For a four-parameter, read-only resolution tool with an output schema, the description covers input forms, the anchoring semantics of reference/timezone, and the cost of invocation. The only meaningful omission is how genuinely ambiguous text (e.g. '3pm' with no date) behaves, though the forward_date parameter in the schema partially covers that.

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 75%, with only the required 'text' parameter lacking a description, and the description compensates by showing valid text forms such as 'in 2 weeks' and a date range. It also adds meaning to 'reference' and 'timezone' by framing them as the anchor against which the text is resolved, beyond the schema's terse default notes.

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 — 'Resolve natural-language dates ... to exact datetimes' — and backs it with three concrete input examples including a range ('Dec 25 to Jan 2'). This clearly separates it from siblings like date_add, date_diff, and timezone_convert, which operate on already-structured 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?

It establishes the calling context ('relative to a reference time and time zone') and shows the shape of acceptable input, so an agent knows what to send. However, it offers no explicit when-not-to-use guidance and never routes the agent to a sibling — e.g. that date_add should be used for arithmetic on known dates rather than natural-language text.

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 closed-world behavior, so the bar is lower. The description still earns credit for disclosing that lunar and government-proclaimed dates are rule-based estimates — an accuracy caveat an agent cannot get from annotations — plus the $0.001 x402 payment cost, which affects invocation decisions.

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?

Three short sentences, front-loaded with what the tool returns and bounded by coverage, followed by the accuracy caveat and cost. Nothing is redundant and nothing buries the important facts.

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 lookup with an output schema, the description covers scope, data-quality caveats and cost — most of what an agent needs. It omits behavior outside the supported range (e.g. a year past 2050 or an unsupported country), which is the only remaining gap.

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 both parameters are already documented, including the year default and the ISO alpha-2 pattern. The description's '207 countries, 2000–2050' restates ranges already present in the schema, adding no format or edge-case detail.

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 names the resource and its two dimensions precisely ('Public holidays for a country and year') and bounds the dataset (207 countries, 2000–2050). It does not explicitly contrast itself with the nearest sibling, business_hours_deadline, though the country parameter text hints at that link.

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 is implied by the stated scope — an agent can infer this is the lookup for holiday calendars — but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to business_hours_deadline as the alternative when business-day math is the actual goal.

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 openWorldHint=false, so the safety profile is covered. The description earns credit for two things beyond that: DST-aware expansion semantics and the per-call cost with the x402 payment scheme, which the agent must know about before invoking. It doesn't disclose occurrence limits or edge-case behavior when the range is exhausted, so it stops short of rich behavioral context.

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 short sentences, front-loaded with the core capability and its vocabulary, followed by the one operational fact (price) an agent needs before calling. Nothing is repeated from the schema and nothing 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?

An output schema exists, so return values need not be explained, and pricing plus payment method are disclosed. However, for a recurring-date expander the practical failure modes (unbounded rules, the 200-occurrence cap, missing time zone defaults) are left entirely to the schema, so an agent must open the schema to call it confidently.

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 would be 3. The description adds real meaning on top: it clarifies that expansion happens in a named time zone and is DST-aware, which explains how timezone and start interact, and it confirms excluded dates are supported as an optional refinement.

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 pairs a precise verb ("Expand") with a precise resource ("an iCalendar RRULE") and illustrates it with examples like "every 2nd Tuesday." That is enough to separate it from date_add or date_diff, but it never distinguishes itself from the closest sibling, cron_schedule, which an agent could plausibly pick for the same recurring-expression task.

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?

Usage is implied by the input format: use this when you have an RRULE string and need concrete occurrences. There is no explicit when-not guidance, no instruction to prefer parse_date_text or cron_schedule for natural-language or cron expressions, and no note about what happens when the RRULE is malformed.

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 closed-world, so safety is covered. The description adds two genuinely extra facts: conversion is DST-aware (a real behavioral risk area) and each call costs $0.001 via x402, a billing/payment behavior nothing in the annotations conveys.

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 with the core purpose front-loaded and no filler. The price note is short and useful, though it sits in the same breath as the functional description rather than being clearly separated.

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?

Output schema exists, so return values need not be explained, and the tool is small (3 params, 1 required). Purpose, DST behavior, timezone naming, and cost are covered; only edge behaviors like omitting from_timezone with a wall-clock string are 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?

At 33% schema coverage, the description must compensate, and 'IANA time zones' clarifies the format expected by both to_timezone and from_timezone, which the schema documents only by example. It also echoes the instant/local-wall-clock distinction from the datetime parameter, though it does not mention that from_timezone is optional or the 'now' 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?

States a specific verb and resource ('Convert ... between IANA time zones') plus qualifiers that define scope: instant vs. local wall-clock input and DST-awareness. This is enough to distinguish it from siblings like city_time or date_add without opening a schema.

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?

Usage is only implied by the stated scope; there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling date/time tools. The cost note gives an implicit call only when conversion is actually needed, but no 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 declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: a $0.001 per-call x402 cost, weekend skipping by default, and a 14-day search cap. It stops short of saying what a payment failure looks like or how many windows are returned.

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?

Three short sentences, front-loaded with purpose then constraints then cost, with no filler. The 'up to 14 days' clause mildly duplicates the schema maximum, but the rest earns its space.

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 return values need no explanation, and the annotations carry the safety profile. What remains thin is the x402 payment mechanic, which is named but not explained, and the unstated defaults for work hours.

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 43%, so the description must compensate and only partly does. It clarifies that participants are optional and carry their own hours, and restates the weekend default and 14-day limit, but work_start/work_end defaults and the date-zone behavior are left entirely to 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: "Find when working hours overlap across time zones (meeting windows)." That is far more precise than siblings like timezone_convert or date_diff, though it never names an alternative tool to route away from.

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 implies usage through constraints (per-participant hours optional, weekends skipped by default, 14-day cap) but never states when to pick this over business_hours_deadline or timezone_convert. The agent must infer the selection rule from the sibling names alone.

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