Skip to main content
Glama

Plan a leave year

plan_leave_year
Read-onlyIdempotent

Plan a whole leave year: the set of breaks that turns the person's annual leave allowance into the most days off, using every bank holiday, with the dates to book for each break and the totals. Handles any leave year start date, part-time working days, three plan styles and school holidays (parents: breaks only in school holidays; school staff: the holidays themselves), from the council's published term dates when you pass council and typical dates otherwise. Use for "Plan my 28 days of leave for 2027, I have kids at school in Leeds".

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": "plan_leave_year"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoWhich leave year: current or next. Defaults to current, or next when under 90 days are left.
styleNomix: two proper holidays of 9+ days, the rest long weekends (default). longWeekends: as many 3–5 day weekends as possible. bigTrips: fewer trips of 9+ days.mix
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 breaks only in the school holidays; staff: works in a school, so the school holidays are the breaks. UK only.none
councilNoWith school: parent or staff. 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. Without it, typical school holidays (Northern Ireland: the Department of Education's dates).
workdaysNoDays the person works, e.g. ["mon","tue","wed","thu"] for a four-day week. Defaults to Monday to Friday.
allowanceNoDays of annual leave (PTO in the US) a year, not counting public holidays. Defaults to the usual for the region: 25 in the UK, 20 in Ireland and Australia (the legal minimum for full-time work), 15 in the US.
days_usedNoDays of this leave year's allowance already taken or booked. Default 0.
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: common.common
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).
leave_year_startingNoInstead of year: the calendar year the leave year starts in, e.g. 2027 for January–December 2027 or April 2027–March 2028.
leave_year_start_dayNoDay of the month the leave year starts. Default 1.
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.
leave_year_start_monthNoMonth the leave year starts, 1–12 (1 = January, 4 = April). Default 1.

Output Schema

NameRequiredDescriptionDefault
notesYes
styleYes
breaksYes
budgetYes
regionYes
schoolYes
sourceYes
totalsYes
councilYesThe council whose published dates are used, or null for typical dates
licenceYes
daysUsedYes
workdaysYes
allowanceYes
leaveYearYes
sourceUrlYes
regionNameYes
assumptionsYes
attributionYesCredit to show with the dates
plannedFromYes
schoolYearsYesWhere each school year's dates come from
bankHolidaysYes
trainingDaysYesThe council's staff training (INSET) days: pupils are off, staff work
schoolHolidaysYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / council
      Added value: +{
      +  "description": "With school: parent or staff. 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. Without it, typical school holidays (Northern Ireland: the Department of Education's dates).",
      +  "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."
    • changedInput schema / properties / school / description
      Previous value: -"none (default); parent: children at school, so breaks only in typical school holidays; staff: works in a school, so the school holidays are the breaks. UK only."New value: +"none (default); parent: children at school, so breaks only in the school holidays; staff: works in a school, so the school holidays are the breaks. UK only."
    • 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"
      +}
    • removedOutput schema / properties / schoolHolidays / items / properties / typical / const
      Removed value: -true
    • addedOutput schema / properties / schoolHolidays / items / properties / typical / description
      Added value: +"True: the usual pattern, not the council's published dates"
    • 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",
      -  "leaveYear",
      -  "plannedFrom",
      -  "allowance",
      -  "daysUsed",
      -  "budget",
      -  "style",
      -  "school",
      -  "workdays",
      -  "totals",
      -  "breaks",
      -  "bankHolidays",
      -  "schoolHolidays",
      -  "assumptions",
      -  "notes",
      -  "source",
      -  "sourceUrl",
      -  "licence",
      -  "attribution"
      -]New value: +[
      +  "region",
      +  "regionName",
      +  "leaveYear",
      +  "plannedFrom",
      +  "allowance",
      +  "daysUsed",
      +  "budget",
      +  "style",
      +  "school",
      +  "workdays",
      +  "totals",
      +  "breaks",
      +  "bankHolidays",
      +  "schoolHolidays",
      +  "assumptions",
      +  "notes",
      +  "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. Changed5 schema fields changed
    • removedInput schema / properties / allowance / default
      Removed value: -25
    • changedInput schema / properties / allowance / description
      Previous value: -"Days of annual leave a year, not counting public holidays. Default 25."New value: +"Days of annual leave (PTO in the US) a year, not counting public holidays. Defaults to the usual for the region: 25 in the UK, 20 in Ireland and Australia (the legal minimum for full-time work), 15 in the US."
    • 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": "common",
      +  "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: common.",
      +  "enum": [
      +    "common",
      +    "federal",
      +    "custom"
      +  ],
      +  "type": "string"
      +}
  4. First observed

TDQS

A4.1/5.0
Behavior4/5

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 goes beyond them by naming data sources (gov.uk bank holidays, Nager.Date, the council's published term dates, Leave Hacker's ONS copy, NI Department of Education) and the fallback to typical dates when no council is given. That source/fallback disclosure is the kind of context annotations cannot carry; only return-value shape is left to the output schema.

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

Conciseness4/5

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

Three sentences, front-loaded with the outcome before the option surface and the usage example. Dense but every clause carries information; the long parenthetical asides about parent/staff modes make it slightly harder to scan than it needs to be.

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 14-parameter tool with an output schema and full annotations, the description covers the important complexity (year start, part-time workdays, styles, school modes, region-dependent holidays) and gives a worked example. What remains unsaid is largely delegated to the schema and output schema, so the gaps are minor.

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 the baseline is 3, and most of the description's parameter content (three plan styles, school modes, region defaults) simply restates the schema. It does add a little cross-parameter framing, such as the parent-vs-staff distinction and the council-drives-term-dates relationship, but not enough to lift it above the baseline.

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?

States a specific verb and resource ("Plan a whole leave year") and immediately defines the deliverable: the set of breaks that maximises days off, the dates to book for each break, and the totals. The scope (whole year, all breaks, using every bank holiday) makes it clearly distinct from a single-day picker like best_days_to_book or a trip finder.

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 an explicit trigger with a realistic user utterance ("Plan my 28 days of leave for 2027, I have kids at school in Leeds") plus scope conditions (UK-only for school modes, US-only for us_holidays). It stops short of naming siblings or stating when to prefer best_days_to_book or find_trips over this tool.

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