Leave Hacker

Best days to book

best_days_to_book

Read-onlyIdempotent

Find the days of annual leave to book around each public holiday (or cluster, such as Christmas and New Year) to get the most days off in a row: "book 4 days, get 10 off" options, cheapest first, with the exact dates. Use for "Which days should I book around Easter 2027 in Scotland?". Filter by holiday name (Easter, Christmas, Early May, Spring, Summer, St Patrick...). Past days are skipped.

Input Schema

Name	Required	Description	Default
`to`	No	End of the date range, inclusive (yyyy-MM-dd).
`from`	No	Start of a date range, instead of year (yyyy-MM-dd).
`year`	No	Calendar year, e.g. 2027. Defaults to this year.
`region`	No	Where the person works: england-and-wales, scotland or northern-ireland for UK bank holidays (from gov.uk); IE for Ireland; an Australian state or territory as AU-NSW, AU-VIC, AU-QLD, AU-WA, AU-SA, AU-TAS, AU-ACT or AU-NT (their public holidays differ a lot); US for US federal holidays; or a two-letter ISO 3166-1 country code such as DE or FR for other countries' public holidays (from Nager.Date). Defaults to england-and-wales.	england-and-wales
`holiday`	No	Only holidays whose name contains this, e.g. "Easter", "Christmas", "May".
`workdays`	No	Days the person works, e.g. ["mon","tue","wed","thu"] for a four-day week. Defaults to Monday to Friday.
`us_holidays`	No	US only: which holidays the person's employer gives. Private employers choose: common = the usual six (New Year's Day, Memorial Day, Independence Day, Labor Day, Thanksgiving, Christmas); federal = all 11 federal holidays; custom = the ones in us_holiday_ids. Default here: federal, to show every option.	federal
`max_leave_days`	No	Most days of leave for one break. Default 9.
`us_holiday_ids`	No	US only, with us_holidays: custom. Any of: new-years-day, mlk-day, washingtons-birthday, memorial-day, juneteenth, independence-day, labor-day, columbus-day, veterans-day, thanksgiving, day-after-thanksgiving, christmas-day (day-after-thanksgiving isn't federal, but many employers give it).
`next_working_day_off`	No	Ireland only: true if the person's employer gives the next working day off when a public holiday falls on a Saturday or Sunday (the civil service and banks do; Irish law doesn't require it, so the employer may give a day within a month, an extra day's leave or a day's pay instead). Adds those days, e.g. Mon 27 and Tue 28 Dec 2027. Default false.

Output Schema

Name	Required	Description
`to`	Yes
`from`	Yes
`notes`	Yes
`region`	Yes
`source`	Yes
`licence`	Yes
`workdays`	Yes
`sourceUrl`	Yes
`regionName`	Yes
`assumptions`	Yes
`attribution`	Yes	Credit to show with the dates
`maxLeaveDays`	Yes
`opportunities`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

addedInput schema / properties / next_working_day_off

Added value: +{
+  "description": "Ireland only: true if the person's employer gives the next working day off when a public holiday falls on a Saturday or Sunday (the civil service and banks do; Irish law doesn't require it, so the employer may give a day within a month, an extra day's leave or a day's pay instead). Adds those days, e.g. Mon 27 and Tue 28 Dec 2027. Default false.",
+  "type": "boolean"
+}

Changed3 schema fields changedOct 26, 2026

changedInput schema / properties / region / description

Previous value: -"Where the person works: england-and-wales, scotland or northern-ireland for UK bank holidays (from gov.uk), or a two-letter ISO 3166-1 country code such as IE, US, DE for other countries' public holidays (from Nager.Date). Defaults to england-and-wales."New value: +"Where the person works: england-and-wales, scotland or northern-ireland for UK bank holidays (from gov.uk); IE for Ireland; an Australian state or territory as AU-NSW, AU-VIC, AU-QLD, AU-WA, AU-SA, AU-TAS, AU-ACT or AU-NT (their public holidays differ a lot); US for US federal holidays; or a two-letter ISO 3166-1 country code such as DE or FR for other countries' public holidays (from Nager.Date). Defaults to england-and-wales."

addedInput schema / properties / us_holiday_ids

Added value: +{
+  "description": "US only, with us_holidays: custom. Any of: new-years-day, mlk-day, washingtons-birthday, memorial-day, juneteenth, independence-day, labor-day, columbus-day, veterans-day, thanksgiving, day-after-thanksgiving, christmas-day (day-after-thanksgiving isn't federal, but many employers give it).",
+  "items": {
+    "enum": [
+      "new-years-day",
+      "mlk-day",
+      "washingtons-birthday",
+      "memorial-day",
+      "juneteenth",
+      "independence-day",
+      "labor-day",
+      "columbus-day",
+      "veterans-day",
+      "thanksgiving",
+      "day-after-thanksgiving",
+      "christmas-day"
+    ],
+    "type": "string"
+  },
+  "maxItems": 12,
+  "type": "array"
+}

addedInput schema / properties / us_holidays

Added value: +{
+  "default": "federal",
+  "description": "US only: which holidays the person's employer gives. Private employers choose: common = the usual six (New Year's Day, Memorial Day, Independence Day, Labor Day, Thanksgiving, Christmas); federal = all 11 federal holidays; custom = the ones in us_holiday_ids. Default here: federal, to show every option.",
+  "enum": [
+    "common",
+    "federal",
+    "custom"
+  ],
+  "type": "string"
+}

First observedOct 25, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavior — and it does: results are ordered cheapest-first, each option carries exact dates, and 'Past days are skipped' is a non-obvious filtering rule. Return shape is left to the output schema, so no further credit is needed there.

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

Conciseness4/5

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

Front-loaded with the core purpose, then the quantified payoff ('book 4 days, get 10 off'), then the example, then the filter note. Three sentences stay on topic with no filler; the parenthetical holiday-name list is slightly long but functional.

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

Completeness4/5

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

For a 10-parameter, all-optional tool with a full output schema and complete annotation coverage, the description supplies purpose, output ordering, exclusions (past days), and a realistic invocation example. It could note that all parameters are optional with sensible defaults (current year, england-and-wales, Mon–Fri), but nothing essential is missing.

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

Parameters3/5

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

Schema coverage is 100% and every parameter is documented in detail (including region codes, workdays, us_holidays modes), so the schema carries the load and baseline is 3. The description adds only marginal value — holiday-name examples ('Easter, Christmas, Early May, Spring, St Patrick...') and an implicit hint at the region parameter via 'Scotland' — while leaving workdays, max_leave_days, us_holidays and next_working_day_off untouched.

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

Purpose4/5

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

States a specific verb and resource with precise scope: find annual-leave days to book around each public holiday (or cluster) to maximize consecutive days off, ranked cheapest first. The concrete example query ('Which days should I book around Easter 2027 in Scotland?') removes ambiguity. It doesn't name or exclude the closest sibling, plan_leave_year, so an agent still has to infer the boundary.

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

Usage Guidelines4/5

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

The example question gives clear context for when this tool applies, and 'Filter by holiday name' shows how to narrow a request. There is no when-not guidance and no explicit routing to alternatives like get_bank_holidays (raw holiday list) or plan_leave_year (whole-year planning), which would have pushed this to a 5.

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

All Leave Hacker tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?