Time of Meeting

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the result includes the skipped dates with reasons and that bank/combined error out for countries without bank data, but the error condition is duplicated from the schema and no pagination, limits, or failure modes beyond that are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler: the operation and its skip rules come first, followed by the return shape. The mode enumeration is somewhat dense but earns its place by mapping to the calendar enum.

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 does not need to detail the return payload, and annotations carry the safety profile; parameters are fully covered by the schema. The only real gap is routing guidance among the many date-arithmetic siblings (add_days, working_days_between, 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 description coverage is 100%, so all four parameters including the calendar enum are fully documented in the schema; baseline 3 applies. The description adds only the 'one country' framing, which slightly clarifies that country selection is single-valued but goes no further than the schema on formats or mode semantics.

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 a specific verb and resource ('add N business days to a date') and constrains scope to 'one country, skipping weekends and public holidays, bank closures, or both.' The sibling add_days is implicitly the calendar-day counterpart and working_days_between the counting counterpart, but neither is named, so the differentiation requires inference.

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 'skipping weekends and public holidays' signals the business-day use case versus plain date arithmetic, and the mode list hints at when to pick bank/combined. However it never states when to use this rather than add_days or working_days_between, and no preconditions are spelled out in the description itself.

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 carry readOnly/idempotent/non-destructive/closed-world, yet the description still adds substantive behavior: working_days skips weekends plus the country's national holidays, the start date is not counted, holidays come from a bundled vacanza/holidays list covering only 2026-2028, and a walk leaving those years returns an error. The worked examples make the counting convention concrete.

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 when-to-use, followed by unit semantics and output shape — a sensible order. It is dense but nearly every sentence adds a distinct rule; only the weeks=7 statement partially duplicates the schema enum description.

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 4-parameter computation tool it covers the counting convention, holiday data source and year limits, error condition, and non-repeat of inputs. Return fields are described even though an output schema exists, which is mild redundancy but not a 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 the baseline is 3, but the description adds real meaning: amount may be negative, weeks means exactly seven calendar days with a worked example, and country is required for working_days yet explicitly unused in days/weeks arithmetic. It does not explain what form country takes beyond the schema's 'ISO code or English country name', which is already covered.

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) and resource (a whole number of days/weeks/working_days to a date), and the phrasing 'the date a number of days ... from another date' cleanly separates it from days_between and working_days_between. An agent can route without opening 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?

Explicit when-to-use clause: 'Use when the user asks for the date a number of days or business days from another date.' That frames the forward-computation case well, but it never names the sibling tools (days_between, working_days_between) as the wrong-choice alternatives, so exclusion 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?

Beyond the read-only/idempotent annotations, the description discloses important behavior: end defaults to today UTC, leap-day handling is specified with examples, parts are negative when end precedes start, and total_days is signed. This is rich, call-relevant 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?

The description is front-loaded with purpose and usage, and the examples earn their place by resolving leap-day ambiguity. However, the final sentences about the result and non-repeated dates are somewhat redundant given the output schema, keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, both parameters are fully documented in the schema, annotations cover the safety profile, and an output schema exists. The description adds the edge-case behavior an agent needs to call and interpret the tool correctly.

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 already 100%, so the baseline is 3, but the description adds useful semantics: end defaults to today UTC, start can represent a birthdate, and the output parts are signed when end is before start. The leap-day example further clarifies how the date parameters are interpreted.

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 calculation: age/duration from start to end expressed as calendar years, months, and days. This clearly distinguishes it from a total-days sibling like 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 gives a clear usage condition: when the user asks for an age or the length of time between two dates in years, months, and days. It does not explicitly name days_between as an alternative or state when not to use it, so it falls 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 cover read-only, idempotent, non-destructive behavior, so the bar is lower; the description nonetheless adds substantial domain behavior: the exact band definitions (9:00–17:00 work, 7–9 and 17–19 early/late, other hours night), consistency with the planner, the labeled result categories, and the fact that public holidays lower the score.

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 purpose, then usage, then behavioral detail, with no filler sentences. Slightly dense and the clause 'Uses the same overlap as the planner' is an oblique reference, but 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, yet the description still summarizes the returned shape (slot label, per-city local start/end, score, holiday flags), which is more than sufficient for a two-parameter read-only 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 100%, so the schema already documents both parameters including the YYYY-MM-DD pattern and the 2–8 city constraints. The description only restates the date format and does not add meaning beyond the schema for city resolution.

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 resource (work-hour overlap), a concrete scope (two to eight cities across time zones, one date), and implies the distinction from time-query siblings like current_time_in_cities or find_best_meeting_time. An agent can identify the operation without opening 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?

Explicitly states the triggering user intent: 'when the user asks when the work hours of several cities overlap on a day.' That gives clear use context, but no sibling is named as an alternative or exclusion (e.g., when to prefer find_best_meeting_time instead).

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 safety (readOnly, idempotent, non-destructive), yet the description still adds real value: it discloses that each city returns an IANA zone, a work-hours flag, a public-holiday flag, and a meeting link. It does not mention the seven-city cap on the target list or any failure behavior for ambiguous city names, which would have pushed this to 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 and a worked example, then the when-to-use clause. The trailing sentence about setting a different meeting length when the invitation is built is marginally tangential but not wasteful enough to penalize heavily.

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 three-parameter read-only tool with full schema coverage, annotations, and an output schema, the description is essentially complete. Minor omissions (the maxItems cap, ambiguity resolution behavior) are already covered in the schema, so their absence here is low-cost.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines the from/to/time semantics including the accepted time pattern and the alternatives fallback for ambiguous cities. The description only implies multiplicity via 'one or more other cities' and the example, adding little syntax or format detail beyond the schema. Baseline 3 applies.

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 local time between cities) and immediately grounds it with a concrete example ('3pm in Warsaw in New York and Bangalore'). This clearly separates it from siblings like current_time_in_cities and business_hours_overlap, which answer different questions.

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 a clear trigger: the user names a time in one place and asks what it is elsewhere, or whether it lands in work hours. It stops short of explicit exclusions, e.g. pointing to business_hours_overlap when the user instead wants to find an overlapping window rather than convert a fixed time.

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, non-destructive and closed-world, and the description is consistent with that (it generates link artifacts rather than mutating stored state). Beyond the annotations it discloses useful behavior: default formats are text/ics/google, an empty array returns only the planner link, qr is opt-in, and each city reports whether the date is a public holiday. It never explicitly says the call persists nothing, but nothing implies otherwise.

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 opening sentence is well front-loaded, but the middle is repetitive: the planner link is defined twice, the four format meanings are restated nearly verbatim from the schema, and the trailing fragment 'The calendar file is https://timeofmeeting.com/c?q=.' ends mid-thought. Several sentences do not earn their place against the already-complete 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?

With an output schema present and full annotation coverage, the description need not explain return values, and what it does say about outputs (holiday flags per city, format ordering) is consistent and helpful. The only gap is the dangling calendar-file URL sentence, which is incomplete rather than absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does add a little framing — duration_minutes mirrors the planner Duration control and is 'chosen now', title is optional and becomes the event name and first text line — but it mostly restates the schema's format descriptions verbatim rather than adding new meaning.

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 first sentence states a specific verb and resource — 'Make a calendar invite for one chosen meeting time across time zones' — and enumerates the concrete artifacts produced (planner link, paste-ready text, .ics, Google Calendar link, QR code). This clearly separates it from siblings like find_best_meeting_time or convert_time, which don't produce shareable invite artifacts.

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 once the meeting time is chosen' gives an explicit precondition that implicitly routes the agent to find_best_meeting_time when a time is not yet picked. It stops short of naming that sibling or stating when-not to use this tool, so it is clear context rather than 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 annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds a genuinely useful behavioral note—that a timeofmeeting.com planner link is returned for the first city—but the remaining sentences describe return fields, which the output schema already carries.

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 trigger are front-loaded in the first two sentences with no filler. The trailing sentence about 'weeks is the ISO week and the US week of the UTC date' is output-field detail that belongs with the output schema and reads slightly out of place here.

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 a full output schema, complete annotations, and one well-documented parameter, the description supplies the purpose, trigger, and the notable planner-link side effect, which is enough to call the tool correctly. The only ambiguity-resolution path (fall back to search_cities for an unknown city) is left implicit.

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 singular 'cities' parameter is documented richly in-schema (1–8 items, comma-separated string accepted, fuzzy spelling/accents, alternatives returned on name collisions). The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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 concrete verb-plus-resource statement ('show the current local time, IANA time zone, UTC offset, work-hour band, and public holiday') and scopes it per city. It is clearly separable from siblings like convert_time, dst_check, or get_holidays because it returns a composite snapshot for named cities rather than converting or checking a single concern.

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 states the trigger condition explicitly: 'Use when the user asks what time it is now in one or more cities.' That is strong when-to-use guidance. It does not name alternatives (e.g., use convert_time for an arbitrary target moment, or search_cities to resolve ambiguous names), so no when-not guidance exists.

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 this as a read-only, idempotent, closed-world operation, and the description goes well beyond them: it explains that the count is exclusive by default, that a negative result means end precedes start, and that leap years shift the answer. This is precisely the off-by-one behavior an agent would otherwise get wrong.

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?

It is front-loaded with the purpose and usage trigger, then layered with the semantics that matter. A few sentences are near-duplicative — the same-day-equals-zero case restates the general exclusivity rule, and 'the result is that count and nothing else' is largely redundant given the output schema — but no sentence is 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?

For a four-parameter date arithmetic tool, the definition covers inputs, defaults, boundary semantics, sign behavior, leap-year behavior, and the identity case. With an output schema present it correctly avoids describing the return shape in detail, so nothing an agent needs to call it correctly 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 already states the defaults, yet the description adds real meaning: worked examples show that include_start/include_end control strict-vs-inclusive boundaries ('2024-02-28 to 2024-03-01 is 1 in a leap year... 3 in that leap-year span' with both true). The parameter descriptions alone ('Count start. Default false.') could not convey 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?

The description opens with a specific verb and resource ('Count calendar days from start to end') and the word 'calendar' implicitly separates it from the sibling working_days_between. An agent can tell immediately that this is a pure day-count, not a business-day or duration-formatting tool.

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 a clear trigger condition: 'Use when the user asks how many days are between two dates.' However, it never names an alternative or exclusion — for example, that business-day counting belongs to working_days_between or that adding an offset belongs to add_days — so the routing is only half-specified.

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 that this is a safe, read-only, idempotent operation. The description adds substantial behavioral context beyond that: the default search window, how weeks is populated or null, what unique/gap/overlap mean for planned_time, when shifted is true, and how utc resolves gaps versus overlaps, including the warning not to treat utc as the only reading.

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 purpose and then moves through defaults, output semantics, and caveats. It is dense and mostly earns its length, though some output-field explanations ('weeks is iso_week and us_week...', 'The change object and a planned time do not repeat the week numbers') are slightly convoluted and could be tightened.

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 complex DST tool with an output schema, the description covers the important gaps: default window, planned_time statuses, shifted behavior, utc resolution, and the warning about ambiguous times. An agent has enough information to invoke it correctly and interpret the key outputs.

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 useful semantics beyond the schema: from and to must be passed together or omitted together, the default window is today UTC through 365 days later, and planned_time is interpreted as a local wall time in the city. City matching behavior is already covered by the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: it says when a city's clocks next change and whether a planned local time is skipped or ambiguous. That planned-time ambiguity check distinguishes it in practice from the sibling get_dst_changes, but the description never names that sibling or explicitly states when to choose one over the other.

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: 'Use for a meeting time near a DST change, or a local time that may not exist or may be ambiguous.' It also explains the from/to pairing and the default 365-day window. It does not explicitly exclude cases or name alternative tools for plain clock-change listings.

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 cover the safety profile (read-only, idempotent, non-destructive); the description adds ranking logic (length is not considered), holiday down-ranking and that the reason is named, per-slot score/reasons, and that exactly one planner link plus next_step is returned. It also rules out calendar files and QR codes, which prevents false expectations.

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 and usage, but the length/exports caveat is stated twice ('Ranking does not take a meeting length' and the closing two sentences about length and formats), and the per-slot return details are spread across several short sentences that restate the same idea.

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 and the description still summarizes the key return fields (link, next_step, score, reasons), so an agent knows what to expect. Minor gaps remain: nothing about invalid or unmatched cities beyond the schema's 'alternatives' note, and no mention of error 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 city-count limits, date formats, defaults and the ambiguity/alternatives behavior all documented in the schema itself. The description only restates the 'two to eight cities' bound and adds nothing about start_date/end_date semantics, so the baseline is 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?

States a specific verb and resource ('propose up to three fair meeting times for two to eight cities') and adds the crucial scope qualifier 'while the slot is still being chosen', which separates it from create_meeting_link. An agent can tell what this returns without opening 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?

Explicit trigger: 'Use when the user wants a time that works for people in different cities and time zones.' It also sets boundaries by saying the meeting length and invitation formats are chosen later, and that no calendar files or QR code are produced. It stops short of naming siblings such as business_hours_overlap or create_meeting_link as the alternative to route to.

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 behavior, so the description's job is to add operational context — and it does: default range of the next year, the 366-day range cap, and the presence of local time plus ISO and US week fields per change. It adds no return format details beyond that, which is acceptable given the output schema exists.

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?

Four tight sentences, front-loaded with the core action, then usage triggers, defaults, and the range constraint. Every sentence carries information an agent needs; nothing is padded.

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 read-only lookup with full schema coverage and an output schema, the description covers purpose, triggers, defaults, and the range limit. The one gap is disambiguation from dst_check, which would make an agent fully confident in tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents city matching, fuzzy spelling, alternatives, and the date formats. The description only restates the date-range default and the 366-day limit, adding little beyond the structured fields — 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?

"List daylight saving time (DST) clock changes for one city" states a specific verb and resource with an explicit scope of one city. It is clear what the tool returns, though it does not explicitly contrast with the sibling dst_check, which an agent could plausibly confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear when-to-use triggers: "when the user asks when the clocks change, or whether a recurring meeting moves when DST starts or ends." No alternative is named (dst_check is the obvious adjacent tool), so it stops just 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?

The annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by explaining that multiple years can be returned together, that regional holidays are included alongside national holidays, and what each holiday record contains. It does not discuss authentication or rate limits, but those are not implied by this data-lookup tool.

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 purpose and usage, and most sentences earn their place. The enumeration of holiday fields is somewhat long and redundant given that an output schema exists, but it does not obscure the core guidance.

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 seven optional parameters, full schema description coverage, an output schema, and rich annotations, the description is complete enough for an agent to select and invoke the tool correctly. It covers purpose, usage conditions, input modes, regional behavior, and output richness.

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 input schema already documents each parameter thoroughly. The description restates the input modes but adds little syntax or meaning beyond what the schema already provides, so the baseline score of 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 states a specific verb and resource: list public holidays for a country, optional ISO 3166-2 region, or city. It also clarifies the scope by describing the use cases of checking whether a date is a holiday somewhere or listing holidays in a year, which makes the tool easy to distinguish from the surrounding date/time tools.

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 when-to-use guidance, such as when the user asks whether a date is a holiday or which days are holidays in a year. It also explains the mutually exclusive input modes: one year, a list of years, or a date range. It does not name sibling alternatives or explicit when-not conditions, but no close sibling appears to require that.

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 readOnlyHint/idempotentHint annotations, it discloses the non-obvious rules that determine the answer: start is inclusive, a rolled-over month is searched if the occurrence already passed, and a nonexistent fifth weekday is skipped. Worked examples for both the same-month and next-month branches make the behavior unambiguous.

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 definition, then examples, then edge cases – a sensible order with little filler. The final sentence listing returned fields ('that date, its month, iso_week, and us_week') is largely redundant given the output schema, costing some tightness.

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?

All three parameters, the default value, the rollover and skip edge cases, and the response shape are covered; the output schema exists, so return values need no further elaboration. An agent has everything needed to call this correctly on the first attempt.

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 enums for weekday and occurrence, so the baseline is 3; the description adds real meaning by explaining that start defaults to today (UTC) and how the occurrence labels interact with the month boundary. The 'request is not repeated' phrasing is a slight deduction because it obscures whether start is echoed back.

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-and-resource statement ('Find the next date on or after start that is the first... or last given weekday of its month') that pins down both the operation and its ordinal-of-month semantics. That framing is clearly distinct from siblings like add_days, days_between, or week_number.

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 an explicit use case ('Use for questions like the date of the last Friday of the month'), so an agent can pattern-match typical requests. It never names an alternative tool or states when another tool is the better choice, so it stops short of 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds little beyond that: the return fields it lists are already in the output schema, and 'The query is not repeated' is cryptic rather than informative.

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, front-loaded sentences with the purpose first and usage second. The trailing sentence 'The query is not repeated' is ambiguous enough that it does not clearly earn 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?

For a one-parameter lookup with full schema coverage, an output schema and complete annotations, the description covers purpose and trigger conditions adequately. It stops short of noting result limits or ranking, which matters when many cities share a name.

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 single 'query' parameter already documents flexible spelling/accents and 'gn:' id acceptance. 'Find cities by name' merely restates that, adding no new 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?

States a specific verb and resource ('Find cities by name') and adds what a result contains ('id, IANA time zone, and country'), which distinguishes it from time-oriented siblings like current_time_in_cities or convert_time.

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 two concrete use conditions: name ambiguity and wanting a city's time zone. It does not name alternatives or state the obvious downstream pattern (using the returned 'gn:' id with convert_time/current_time_in_cities), so the agent must infer that link.

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=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that by defining exactly what the response contains and nothing more, and by spelling out the ISO (Monday start, first-Thursday week 1) and US (Sunday start, 1 January is week 1) conventions with worked edge cases.

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 is returned and when to use it, then the ISO/US definitions. The concrete dates (2026-12-31, 2022-01-01, 2027-01-01) earn their place by disambiguating week-53 and year-boundary behavior that an agent would otherwise guess at. Slightly example-heavy, but 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?

The tool is trivial to invoke: one fully documented parameter, an output schema, and rich annotations. The description supplies the only thing structured fields cannot — the definitional rules for ISO vs US week numbering at year boundaries. Missing only error behavior for malformed dates, which the schema pattern largely handles.

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 single parameter's pattern (^\d{4}-\d{2}-\d{2}$) and description ('Calendar date, YYYY-MM-DD') already fully specify the input. The description only restates 'one YYYY-MM-DD date' without adding syntax, timezone, or range semantics, so the baseline 3 applies.

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 only iso_week and us_week for one YYYY-MM-DD date') and explicitly bounds the output ('no date, weekday, year, or link'). That scope is disjoint from every sibling tool, which do arithmetic, conversions, holidays, or meeting scheduling rather than week-number lookup, so an agent can select it without ambiguity.

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 a clear triggering condition: 'Use when the user asks for the week number of a date.' It does not name an alternative or a when-not case, but the tool's narrow purpose makes exclusion unnecessary 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 destructiveHint=false, and the description does not contradict them. It adds that skipped dates are returned with reasons, but since an output schema exists that fact is largely redundant, and no rate limits, error behavior, or range limits appear beyond what the schema already says about unsupported bank calendars.

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 front-loaded sentence that puts the core action first and tucks clarifications into a trailing parenthetical. It is dense but every clause carries content; the parenthetical enum restatement is the one mildly redundant piece.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (6 params, 3 required, fully documented schema, output schema present, safe read annotations), so the description only needs to establish purpose. That it does well; the remaining gap is routing guidance among several date-arithmetic siblings, which the description never addresses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter including defaults, patterns, and enum semantics, so the baseline is 3. The description only restates the calendar enum values ('business, bank, combined') without adding format, boundary, or inclusivity detail beyond what the schema documents.

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 business/working days between two dates for one country, with weekend and holiday skipping. The 'business days' framing implicitly separates it from the calendar-day sibling days_between, but it never names that sibling or add_business_days, so differentiation is left to inference.

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 'for one country' plus the calendar modes, and the schema notes that bank/combined error for unsupported countries. There is no explicit when-to-use versus days_between, add_business_days, or get_holidays, and no stated prerequisites such as needing a country code.

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