Skip to main content
Glama

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. For parents in the UK, school: parent keeps leave inside the school holidays, using the council's published term dates when you pass council.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "best_days_to_book"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoEnd of the date range, inclusive (yyyy-MM-dd).
fromNoStart of a date range, instead of year (yyyy-MM-dd).
yearNoCalendar year, e.g. 2027. Defaults to this year.
regionNoWhere 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, or to the council's nation when council is given.
schoolNonone (default); parent: children at school, so leave is only booked in the school holidays. UK only. School staff can't book leave in term: use plan_leave_year with school: staff.none
councilNoWith school: parent. The UK council whose term dates the school follows: its name ("Surrey", "Edinburgh"), its id ("surrey", "city-of-edinburgh") or the first half of a postcode ("GU1", "EH1"), looked up in Leave Hacker's own copy of the ONS list. Send only the first half of a postcode, not the full one.
holidayNoOnly holidays whose name contains this, e.g. "Easter", "Christmas", "May".
workdaysNoDays the person works, e.g. ["mon","tue","wed","thu"] for a four-day week. Defaults to Monday to Friday.
us_holidaysNoUS 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_daysNoMost days of leave for one break. Default 9.
us_holiday_idsNoUS 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_offNoIreland 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

NameRequiredDescriptionDefault
toYes
fromYes
notesYes
regionYes
schoolYes
sourceYes
councilYesThe council whose published dates are used, or null for typical dates
licenceYes
workdaysYes
sourceUrlYes
regionNameYes
assumptionsYes
attributionYesCredit to show with the dates
schoolYearsYesWhere each school year's dates come from
maxLeaveDaysYes
trainingDaysYesThe council's staff training (INSET) days: pupils are off, staff work
opportunitiesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / council
      Added value: +{
      +  "description": "With school: parent. The UK council whose term dates the school follows: its name (\"Surrey\", \"Edinburgh\"), its id (\"surrey\", \"city-of-edinburgh\") or the first half of a postcode (\"GU1\", \"EH1\"), looked up in Leave Hacker's own copy of the ONS list. Send only the first half of a postcode, not the full one.",
      +  "maxLength": 80,
      +  "minLength": 2,
      +  "type": "string"
      +}
    • removedInput schema / properties / region / default
      Removed value: -"england-and-wales"
    • 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); 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."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, or to the council's nation when council is given."
    • addedInput schema / properties / school
      Added value: +{
      +  "default": "none",
      +  "description": "none (default); parent: children at school, so leave is only booked in the school holidays. UK only. School staff can't book leave in term: use plan_leave_year with school: staff.",
      +  "enum": [
      +    "none",
      +    "parent"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / council
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "id": {
      +          "type": "string"
      +        },
      +        "name": {
      +          "type": "string"
      +        },
      +        "nation": {
      +          "type": "string"
      +        },
      +        "short": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "name",
      +        "short",
      +        "nation"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The council whose published dates are used, or null for typical dates"
      +}
    • addedOutput schema / properties / school
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / schoolYears
      Added value: +{
      +  "description": "Where each school year's dates come from",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "checked": {
      +        "description": "yyyy-MM-dd the dates were last checked against it",
      +        "type": "string"
      +      },
      +      "council": {
      +        "type": "string"
      +      },
      +      "note": {
      +        "type": "string"
      +      },
      +      "schoolYear": {
      +        "description": "e.g. \"2026/27\"",
      +        "type": "string"
      +      },
      +      "source": {
      +        "description": "council: the council's published term dates; typical: the usual pattern, not official",
      +        "enum": [
      +          "council",
      +          "typical"
      +        ],
      +        "type": "string"
      +      },
      +      "sourceUrl": {
      +        "description": "The council's own page or PDF",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "schoolYear",
      +      "source"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / trainingDays
      Added value: +{
      +  "description": "The council's staff training (INSET) days: pupils are off, staff work",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "date": {
      +        "description": "yyyy-MM-dd",
      +        "type": "string"
      +      },
      +      "label": {
      +        "description": "e.g. \"Fri 26 Mar 2027\"",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "date",
      +      "label"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "region",
      -  "regionName",
      -  "from",
      -  "to",
      -  "maxLeaveDays",
      -  "workdays",
      -  "opportunities",
      -  "assumptions",
      -  "notes",
      -  "source",
      -  "sourceUrl",
      -  "licence",
      -  "attribution"
      -]New value: +[
      +  "region",
      +  "regionName",
      +  "from",
      +  "to",
      +  "maxLeaveDays",
      +  "workdays",
      +  "opportunities",
      +  "assumptions",
      +  "notes",
      +  "school",
      +  "council",
      +  "schoolYears",
      +  "trainingDays",
      +  "source",
      +  "sourceUrl",
      +  "licence",
      +  "attribution"
      +]
  2. Changed1 schema field changed
    • 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"
      +}
  3. Changed3 schema fields changed
    • 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"
      +}
  4. First observed

TDQS

A3.9/5.0
Behavior3/5

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 real behavior beyond that: results are ordered cheapest first, past days are skipped, term dates come from the council's published data, and it names data sources. Still, it does not describe output structure, defaults' effect on breadth, or error behavior when council lookup fails.

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-loads the core benefit and the example query, and each sentence carries distinct information (filtering, past days, school mode). The final parent/school sentence is dense but earns its place; a little could be trimmed where it duplicates schema text.

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?

With 12 optional parameters, full schema coverage, an output schema, and rich annotations, the description gives enough context to call it correctly across regions and school modes. Minor gaps remain on default interactions (e.g., year vs from/to precedence) that the description does not clarify beyond the schema.

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 description coverage is 100%, so every parameter is already documented in detail, including the school/council coupling and US/IE specifics. The description adds little beyond the schema and partly repeats it; baseline 3 is correct.

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

Purpose5/5

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

A specific verb-plus-resource statement: find annual-leave days to book around each public holiday to maximize consecutive days off, sorted cheapest first, with exact dates. The 'book 4 days, get 10 off' phrasing makes the output shape concrete and clearly distinguishes it from get_bank_holidays or find_trips.

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?

Gives a concrete use case ('Which days should I book around Easter 2027 in Scotland?') plus filtering guidance. It routes school staff to the sibling plan_leave_year with school: staff, which is explicit alternative routing, but it does not say when to reach for get_bank_holidays or find_trips instead.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources