Leave Hacker

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds genuine context beyond that: results are ordered cheapest-first, clusters like Christmas/New Year are merged, past days are skipped, and exact dates are returned. It does not discuss result size, pagination, or what happens when no qualifying break exists, so it adds value without being 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?

One dense paragraph, front-loaded with the purpose and the differentiating output shape, followed by the example query and filters. Every clause carries information, though the parenthetical list of holiday names and the appended 'Past days are skipped' tack onto an already long sentence rather than being 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?

An output schema exists, so return structure needn't be explained, and the description still conveys ordering, clustering, and the past-day exclusion. With zero required parameters and full schema coverage, an agent has enough to invoke it correctly; only edge behavior (empty results, result limits) is unaddressed.

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 of the 7 parameters fully documented including region formats, workday enums, defaults and max_leave_days bounds, so the baseline is 3. The description only reinforces the holiday name filter with extra examples (Early May, Spring, Summer, St Patrick) and the region example (Scotland); it never mentions workdays or max_leave_days, so it adds little 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 ('Find the days of annual leave to book') and resource (public-holiday-adjacent leave options) with the exact output shape: "book 4 days, get 10 off" options, cheapest first, with exact dates. That result signature distinguishes it from get_bank_holidays (which surfaces holidays, not leave windows) and from plan_leave_year (year-level planning), so an agent can route without opening schemas.

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 concrete trigger query ("Which days should I book around Easter 2027 in Scotland?") and the filter vocabulary (holiday name, region) that matches that case. It also notes past days are skipped, which clarifies behavior for retrospective ranges. No explicit when-not or named alternative sibling is given, 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 only cover the safety profile (readOnly, idempotent, openWorld, non-destructive); the description adds material behavior the annotations cannot convey: prices are cached airline fares in GBP, can change, may be flagged 'sample' as example-only data, and links are affiliate links via leavehacker.app/go with a disclosure obligation. These are exactly the disclosures an agent needs before quoting fares to a user.

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?

Core purpose and result shape are front-loaded, and the affiliate/staleness caveats earn their place. However, the middle is a run-on comma-spliced chain that could be split or tightened without losing content.

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

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

For a 4-param read tool with an output schema, the description covers everything that matters: what is returned (one cheapest fare per destination, ordered), data freshness caveats, currency, and the affiliate link behavior the agent must disclose. Return-value detail is correctly left to the output 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 origin/depart/return/limit are already fully documented with formats and examples. The description adds only result-shaping context (one per destination, cheapest first, GBP) rather than parameter meaning, 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?

States a specific verb and resource ('Find the cheapest return flights from a departure airport') and adds the result shape: one per destination, cheapest first, with booking links. That is enough for an agent to distinguish it from every sibling, none of which return fares.

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 concrete trigger example ('Find cheap flights from Manchester that fit the May bank holiday weekend') and an explicit prerequisite: derive the break's dates with best_days_to_book first. It does not state any when-not condition (e.g. one-way or multi-city trips), so it falls 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 declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond annotations: the external data sources and the three-year maximum range, though it does not cover error behavior or response shape.

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, followed by a concrete example and a key constraint. Every sentence earns its place with no redundant or vague wording.

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 rich schema descriptions, full annotations, and an output schema, the description provides everything needed to select and invoke the tool correctly. It covers purpose, sources, region types, date modes, and range limits without duplicating structured fields.

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 meaning by clarifying the two query modes (year vs. between two dates), the up-to-three-year range limit, and how region maps to UK regions versus ISO country codes.

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 bank holidays or public holidays for a region in a year or date range. It also names the underlying sources (gov.uk vs. Nager.Date) and outputs (weekdays and substitute days), which clearly distinguishes it from sibling tools like get_school_holidays.

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 context with an example question, so an agent knows this is for bank/public holiday queries. However, it does not explicitly say when not to use it or name alternatives such as get_school_holidays or plan_leave_year.

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 the safety profile is covered. The description adds the trait that matters most here: the returned dates are a usual pattern, not official, because councils and schools set their own — plus a mandatory disclaimer to relay. That is real behavioral context beyond structured fields.

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: the first establishes what is returned, the second immediately qualifies accuracy and prescribes the disclaimer. The non-authoritative caveat is front-loaded where it cannot be missed, and 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?

Output schema exists, annotations are rich, and both parameters are fully described in schema. The one thing an agent must know before presenting this data — that the dates are indicative and users must verify — is stated explicitly, so nothing critical 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 description coverage is 100% (year with range and default, region as a three-value enum), so the schema does the work. The description's 'a UK nation in a year' merely mirrors both parameters rather than adding format or selection nuance, which is fine but earns baseline-plus only.

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 resource (typical state-school holiday dates: half terms, Easter, summer, Christmas) scoped to a UK nation and a calendar year. That resource is unmistakably distinct from the sibling get_bank_holidays, so an agent can route 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?

The description tells the agent how to present results ('always tell the person to check their school's term dates') and implies a planning/approximation context, but never names an alternative tool or an explicit when-to-use condition versus get_bank_holidays or plan_leave_year. Usage is left to 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior: the message is phrased in the app's own wording, and break_start/break_end are derived from weekends and bank holidays unless supplied. It stops short of describing the output shape, but an 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?

Two sentences, front-loaded with the purpose, with no filler. The second sentence is dense but every clause (derivation, region, override) 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?

With 4 parameters at full schema coverage and an output schema present, the description covers the remaining gap: how break boundaries are computed and what the tool actually returns conceptually. Nothing critical 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 baseline is 3, but the description adds real meaning beyond the schema: it explains the derivation rule linking dates_to_book, region, and the optional break_start/break_end parameters, which the schema alone does not convey.

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 deliverable: 'Write the short, polite message asking a manager for the leave days of a break.' This clearly separates it from computation siblings like best_days_to_book and plan_leave_year, though it never names a sibling 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?

Usage is implied by the deliverable ('write the message'), and it tells you to 'pass the dates to book', but there is no explicit when-to-use/when-not guidance or reference to the sibling tools it complements.

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 is a safe, idempotent, non-destructive read, so the description doesn't need to argue safety. It adds genuinely useful behavior context: bank holidays sourced from gov.uk for UK regions and Nager.Date for other ISO codes, arbitrary leave-year start dates, part-time workday patterns, and a UK-only restriction on school modes.

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 resource, followed by a tight enumeration of capabilities and a quoted example. Dense but not padded; every clause carries information, though the parenthetical school-mode gloss partially duplicates schema text.

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?

Ten optional parameters and a present output schema mean the return shape needn't be re-explained, and the description correctly avoids that. It covers the behavioral surface an agent needs (region sources, school constraints, part-time days, styles), with the only real gap being the year-vs-leave_year_starting precedence.

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 every parameter is already documented at the source, which sets the baseline at 3. The description references the capability areas (plan styles, school modes, leave year start) but adds no syntax, interaction rules, or precedence guidance beyond the schema—notably it doesn't clarify how `year` and `leave_year_starting` interact when both are supplied.

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 ('Plan a whole leave year') and defines the output scope: the set of breaks optimizing days off, booking dates, and totals. It implicitly separates itself from narrower siblings like best_days_to_book and find_trips by scoping to a full-year plan, but never names an alternative 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?

Provides a concrete triggering utterance ("Plan my 28 days of leave for 2027, I have kids at school") that makes the intended invocation context unmistakable. It does not state when NOT to use it or route the agent to best_days_to_book for single-day questions, so the exclusion side is missing.

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