Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@holiplan Here's my ledger. What do the 2027 school holidays look like, and what can I afford?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for planning a family's year around school holidays and a limited leave allowance.
Assistants are good at suggesting destinations and bad at remembering that Whit Monday is a public holiday, that five carried-over days expire in June, and that you already said no drive over three and a half hours. This server does the parts that should be calculated; the assistant does the parts that need judgement.
Holiday data comes from OpenHolidays (CC BY 4.0), which covers public and school holidays for a growing list of countries, with no API key.
Pre-release (0.1). Stateless: your ledger is a JSON file you keep, and the server stores nothing. See PRIVACY.md for exactly what goes where, and docs/examples.md for what a conversation looks like.
Related MCP server: business-day-mcp
Install uv, then add holiplan to
claude_desktop_config.json and restart Claude:
{
"mcpServers": {
"holiplan": {
"command": "uvx",
"args": ["holiplan"]
}
}
}uvx fetches holiplan from PyPI and runs it; there is nothing else to install. Without uv,
pip install holiplan and use "command": "holiplan" with no args.
Start with the Set up my family profile prompt, which builds a ledger with you one
question at a time, or copy examples/ledger.example.json to my-ledger.json and edit it.
Tell Claude where the file is, and save the updated ledger whenever Claude hands it back.
A conversation then looks like:
Here's my ledger. What do the 2027 school holidays look like, and what can I afford?
Add two weeks on the Danish coast from 17 July.
What needs booking next?
docs/examples.md has these conversations in full, with real figures.
Tool | Purpose |
| School holidays (official and effective dates), single-day closures, and public holidays marked local, half-day and observed |
| Leave days a given trip needs, with the holidays inside it listed |
| The leave days that buy the most time off, and whether the kids are off too |
| Planned versus available leave, including carryover expiry |
| Add or update a trip, then re-check the ledger |
| Overlaps, budget breaches, bad dates, trips outside school holidays |
| Booking deadlines and cancel-by dates, soonest first |
| The whole plan at a glance, for a brief to your partner |
| The plan as a calendar file |
Resources: JSON schemas for the ledger, profile and trip (holiplan://schema/...), and a blank
starter ledger (holiplan://ledger/starter).
Prompts: Set up my family profile, Plan my year, Plan this holiday window, What needs doing next?, Make a brief for my partner.
The ledger is the source of truth. Tools take it in and hand it back, so the plan doesn't drift between conversations.
Intent decides leave. A week with intent home or camp occupies a school holiday
window without costing leave. Override with takes_leave.
Carryover is spent first, but only by trips ending before the expiry date, so "these days expire in June" shows up as a warning while you can still act on it.
A trip over New Year costs each year only its own days.
Local holidays follow your home town. Some holidays cover only part of a region, like
Augsburg's Peace Festival in Bavaria. With the profile's home set to a town, only that
town's local holidays count as days off; without a home they all do. Set local_holidays
to "include" or "exclude" to override. ignore_holidays ("MM-DD") covers what the
data can't tell apart, such as Assumption Day ("08-15"), which is only a holiday in
Catholic-majority Bavarian towns.
School windows include the free days around them. The official Monday-to-Friday dates are stretched over adjacent weekends and public holidays before trips are checked against them. School holidays of two school days or fewer, like All Souls' Day in Austria, are listed separately as closures.
Half-day holidays cost half a day. Zürich's Sechseläuten afternoon is a half day off, not a full one.
Regions accept ISO codes. OpenHolidays uses its own codes where they differ (Vienna is
AT-WI, not AT-9); either works, and an unknown region is an error rather than a quietly
incomplete year.
Ledgers are versioned. Older ledgers are migrated when read, a newer one is refused, and a malformed one gets an error naming the trip and field at fault.
When OpenHolidays is down, the server serves the last copy it fetched, or says plainly that it can't check dates right now. It never guesses.
No real names. Children are identified by alias and interests only.
The server never books anything. It knows what needs booking and by when; you book it and record the result.
Drive-time filtering (OpenRouteService or self-hosted OSRM)
Remote deployment over Streamable HTTP
Publish to the MCP registry
School holiday windows by school type, where the data supports it (Zürich splits primary, secondary and vocational; windows already list the types they apply to)
git clone https://github.com/adekola/holiplan.git
cd holiplan
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m unittest discover -s tests # offlineTo run your working copy in Claude Desktop, point command at the venv's Python
(.venv/bin/python, or .venv\Scripts\python.exe on Windows) with
"args": ["-m", "holiplan.server"].
MIT, see LICENSE. Holiday data: OpenHolidays, CC BY 4.0.
Leave days needed to be away from start to end (inclusive).
Accounts for weekends, public holidays inside the trip, and any half days, part-time pattern or local-holiday settings in the ledger's profile.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| start | Yes | ||
| ledger | No | ||
| region | No | ||
| country | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden and does well by disclosing that weekends, public holidays, half days, part-time patterns, and ledger-profile settings are accounted for. It does not cover error conditions or prerequisite configuration, keeping it short of 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?
The definition is two sentences, front-loads the core purpose, and uses the second sentence for computation details without filler. It is efficient, though not perfectly polished.
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 no annotations, 0% schema descriptions, five parameters, and only three required, the description is not complete enough for reliable invocation. It omits country/region semantics and usage context, though the existing output schema covers return values.
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 0%, so the description must compensate, but it only explains `start` and `end` and hints at `ledger` via profile settings. The required `country` parameter and optional `region` parameter are not mentioned at all, leaving significant parameter semantics undocumented.
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 computation: leave days needed between `start` and `end` inclusive, with factors considered. It does not distinguish this tool from siblings like `get_year_budget` or `find_bridge_days`, so it misses the top score.
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 gives no explicit when-to-use guidance, no exclusions, and does not name any alternative sibling tools. Usage is only implied by the calculation purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the whole ledger: overlaps, budget breaches, bad dates, and trips that fall outside the school holidays.
Run this before telling the user a plan works.
| Name | Required | Description | Default |
|---|---|---|---|
| ledger | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose the actual validation rules applied (overlaps, budget breaches, dates, holiday bounds), which is real behavioral content. It does not state side-effect freedom or error/failure behavior, so a small gap remains.
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 tight sentences: the check list first, the call-to-action second. Nothing is redundant or 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?
An output schema exists, so return values need not be described, and the check list is informative. But with a nested, undocumented `ledger` object and no annotations, the definition is thin on what input is actually valid.
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 0% and the single `ledger` parameter is a nested, open object, so the description must compensate. "The whole ledger" implies the full document is required, but nothing describes its expected shape or required fields, leaving the agent to guess what to pass.
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 (validate) and resource (the whole ledger), then enumerates exactly what is checked: overlaps, budget breaches, bad dates, out-of-holiday trips. No sibling does validation, so an agent can route here without inspecting other 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?
"Run this before telling the user a plan works" gives a clear trigger condition tied to the workflow. It stops short of naming alternatives or exclusions (e.g. per-trip checks vs. whole-ledger), so it is strong 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.
The ledger as an .ics calendar file the user can import.
Returns file contents -- tell the user to save it and import it.
| Name | Required | Description | Default |
|---|---|---|---|
| ledger | Yes | ||
| include_deadlines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one important non-obvious trait: the tool returns file *contents* rather than writing a file, and the user must save/import it. However, it says nothing about whether include_deadlines changes the output, whether the ledger is mutated, or any size/permission constraints.
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 short sentences, front-loaded with what the tool produces and followed by the one operational instruction the agent needs. Nothing is redundant or 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?
An output schema exists, so return-value shape need not be described, and the ledger parameter is a loose nested object. Still, for a two-parameter export tool the description omits the meaning of include_deadlines and any note on ledger contents, leaving a real 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 description coverage is 0% and neither of the two parameters is mentioned. The description does not explain what the 'ledger' object should contain or what toggling 'include_deadlines' (default true) does to the exported calendar, leaving both parameters entirely undocumented across schema and 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 names the resource (the ledger) and the output artifact (.ics calendar file the user can import), so the purpose is unambiguous. It does not differentiate itself from siblings like summarise_plan or list_deadlines, but no sibling overlaps this export behavior, so the distinction is implicit.
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?
There is no statement of when to use this versus alternatives (e.g., list_deadlines for reading deadlines in-app versus exporting them). The only guidance is post-invocation handling ('tell the user to save it and import it'), which is instruction for the agent's response, not selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The leave days that buy the most time off, best value first.
Each option says which days to take off, the stretch that buys, days off
per leave day, the public holidays that make it a bridge, and school:
"holiday" when the children are off school for all of it, "partly", or
"term". Pass the ledger so the parent's work pattern, half days and
local holidays count. Options can overlap -- they are alternatives.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| limit | No | ||
| ledger | No | ||
| region | No | ||
| country | Yes | ||
| max_leave_days | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that options may overlap and are alternatives, and that the ledger changes results by counting work patterns, half days and local holidays. It does not state that the operation is read-only/side-effect-free or how results are computed, but for a query-style tool this is a reasonable disclosure level.
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 value proposition is front-loaded ('The leave days that buy the most time off, best value first'), and the rest flows logically. It is slightly wasteful because it enumerates returned fields that an output schema already documents, but it remains tight and readable.
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 6-parameter optimization tool with 0% schema coverage, the description leaves critical inputs (limit, max_leave_days, region) unexplained. It does detail the return shape, but with an output schema present that is redundant, so the net effect is an incomplete definition of how to invoke it 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 description coverage is 0% across 6 parameters, so the description must compensate and it largely does not. It explains the role of 'ledger' and implies 'country'/'year', but says nothing about 'limit', 'region', or 'max_leave_days', leaving half the parameters undocumented anywhere.
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 the resource and the optimization goal clearly: leave days that buy the most time off, ranked best-value-first. An agent can infer it is a discovery/ranking tool rather than a cost calculator. However, it never names or distinguishes itself from siblings like get_holiday_windows or calculate_leave_cost, so the boundary is left implicit.
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?
There is a single operational hint ('Pass the ledger so the parent's work pattern, half days and local holidays count') but no explicit when-to-use vs alternatives guidance against the many siblings. The 'options can overlap -- they are alternatives' note describes the output, not tool selection. No conditions for choosing this over get_holiday_windows or calculate_leave_cost are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
School holiday windows and public holidays for a region and year.
Use this to frame the year before discussing destinations. region is a
subdivision code such as "DE-BY" (Bavaria) or "AT-WI" (Vienna; the ISO code
"AT-9" works too). Pass the profile's home (the family's town) when known.
Each school window has its official dates and its effective dates, stretched
over the weekends and public holidays that touch it -- the days the family
can actually be away. Holidays of two school days or fewer are listed
separately as school_closures. Public holidays marked local apply to only
part of the region; observed says whether the home keeps them, and is null
when there is no home to check -- then ask the family.
| Name | Required | Description | Default |
|---|---|---|---|
| home | No | ||
| year | Yes | ||
| region | No | ||
| country | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and largely meets it: it explains that each window has official vs effective dates stretched over adjacent weekends/holidays, that short closures are surfaced separately as school_closures, and that local/observed flags encode whether the home keeps a holiday. It even tells the agent to ask the family when observed is null. It omits auth/rate-limit style operational traits, but for a data-read tool the semantic disclosure is strong.
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?
Purpose is front-loaded in the first sentence, followed by usage and then output semantics in a logical order. It is moderately long but each clause conveys non-obvious meaning; the densest sentence about effective dates is justified by real behavioral 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?
An output schema exists, so return structure need not be restated, and the description sensibly focuses on interpreting that output (effective vs official dates, local/observed, school_closures). Combined with parameter format guidance and a usage cue, it is nearly complete for a 4-parameter read tool, lacking only explicit mention of required country/year 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 description coverage is 0%, so the description must compensate, and it does for the ambiguous parameters: region is defined with concrete examples ("DE-BY", "AT-WI", and that ISO "AT-9" also works) and home is explained as the profile's town to pass in. country and year go unexplained, but they are self-evident from context.
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 opening line names a specific resource and scope: school holiday windows plus public holidays, bounded by region and year. It is instantly distinguishable in function, though it never explicitly contrasts itself with siblings like find_bridge_days or get_year_budget, so it stays at 4 rather than 5.
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 this to frame the year before discussing destinations" gives a clear situational trigger for reaching for the tool. It stops short of naming alternatives or stating when-not to use it, so no exclusion guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leave planned versus available for a year, including carryover expiry.
Answers "can we afford all of this?" -- call it after every change.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| ledger | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds useful context about carryover expiry and implies a read-only affordability check, but it does not state side effects, permissions, or mutation behavior. The output schema covers return values, reducing the remaining gap.
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 brief sentences, front-loaded with what the tool does and then when to use it. There is no filler, and the structure is easy to parse.
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 description covers purpose and usage, and an output schema exists so return values need not be explained. However, for a tool requiring a nested ledger object with 0% schema description coverage, the invocation remains ambiguous because the main input is not described.
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 0%, so the description must explain the two required parameters. It only hints at the year parameter ('for a year') and gives no explanation of the required ledger object or its nested contents, leaving the main input undocumented.
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 clearly states it compares planned versus available leave for a year, including carryover expiry. It is more specific than the name alone, but it does not explicitly distinguish itself from siblings like calculate_leave_cost or check_ledger.
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: answer whether the plan is affordable and call it after every change. This tells the agent when to invoke it, though it names no alternatives or when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dated actions the plan implies: booking deadlines and cancel-by dates.
Use it to answer "what needs doing next?".
| Name | Required | Description | Default |
|---|---|---|---|
| today | No | ||
| ledger | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the kind of output (booking deadlines and cancel-by dates) and implies a read-only listing through 'list' and the usage context, but it does not state side effects, permissions, or whether the operation is purely non-destructive.
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 two short sentences with no wasted words. The core output description is front-loaded, followed by a concise usage cue.
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 values need not be explained in depth. However, with no annotations, 0% schema description coverage, and a required nested ledger object, the description is too sparse to explain the required input or important behavioral constraints for correct invocation.
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 0%, and the description adds no meaning for the two parameters. The required nested 'ledger' object and optional 'today' parameter are left entirely undocumented, so an agent gets no help from the description about what to pass.
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 resource and output type: 'Dated actions the plan implies: booking deadlines and cancel-by dates.' This distinguishes it reasonably well from siblings like get_holiday_windows or calculate_leave_cost, though it does not explicitly name itself as the deadline-listing tool beyond the name.
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 one clear usage context: 'Use it to answer "what needs doing next?"'. However, it does not explain when to prefer it over alternatives such as summarise_plan or check_ledger, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The whole plan at a glance, for a brief to a partner or a quick recap.
Returns the family, leave per year, every trip with its leave cost and
booking state, each school window with the plans in it, open_windows
still to decide, issues, and overdue and upcoming deadlines. Turn it into
prose; don't recalculate any figure in it.
| Name | Required | Description | Default |
|---|---|---|---|
| today | No | ||
| ledger | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the burden, and it does well: it enumerates exactly what the output contains (family, leave per year, trips with cost and booking state, windows, open_windows, issues, deadlines) and adds the notable constraint 'Turn it into prose; don't recalculate any figure in it'. That last instruction is valuable behavioral guidance not captured anywhere else.
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 one-line purpose, then a compact enumeration of output contents. Every sentence earns its place, though the output list is longish and could be tightened given an output schema exists.
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?
A read-only summarization tool with an output schema, so return values needn't be explained — yet the description spends most of its length detailing output contents, while leaving the required 'ledger' input unexplained. Adequate overall but incomplete on the input side.
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?
Two parameters with 0% schema description coverage and no explanation in the description. 'ledger' and 'today' are completely undocumented — the description never explains what 'ledger' is, what 'today' defaults to, or why 'today' matters. This is a significant gap for a nested-object required parameter.
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 purpose: 'The whole plan at a glance, for a brief to a partner or a quick recap', naming the scenario (briefing, recap). It's a summarization/aggregation tool distinct from siblings like get_year_budget or check_ledger, though it doesn't explicitly name what it differs from.
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?
Implies use for a brief or quick recap, giving context but no explicit when-to-use vs alternatives (e.g., why summarise_plan instead of calling get_year_budget + list_deadlines). Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update one trip in the ledger, then re-check the whole ledger.
Returns the updated ledger plus any issues. Hand the ledger back to the user so they can save it.
| Name | Required | Description | Default |
|---|---|---|---|
| trip | Yes | ||
| ledger | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses a mutation, an automatic whole-ledger re-validation, the return of updated ledger plus issues, and the crucial fact that the tool does not persist results itself (the user must save). Missing only details like permission requirements or failure behavior.
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 sentences, front-loading the core action before the side effect and return behavior. The instruction about handing the ledger back is actionable rather than filler, though it slightly overlaps the return-value statement.
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 values need not be explained (and the description partly repeats them anyway). For a mutation tool with no annotations and two fully undocumented nested object parameters, the description covers behavior and persistence but leaves the input contract unexplained.
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 0% and both parameters are nested objects with additionalProperties allowed, so the description is the only source of shape information. It conveys only that 'trip' is one trip and 'ledger' is the whole ledger, giving no field-level semantics for either object.
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-resource pair (add or update one trip in the ledger) and states the side effect of re-checking the ledger, which separates it from the read-only sibling check_ledger. It does not explicitly name alternatives, but the core purpose is unambiguous.
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 'Add or update one trip' and by the instruction to hand the ledger back for saving, so an agent can infer this is the write path. However, there is no explicit when-to-use guidance and no mention of when to prefer check_ledger or the other planning siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0calculate_leave_costcheck_ledgerexport_icsfind_bridge_daysget_holiday_windowsget_year_budgetlist_deadlinessummarise_planupsert_tripScored across 9 tools
Most tools have clearly distinct purposes: holiday lookup, leave-cost calculation, bridge-day discovery, budgeting, trip upsert, validation, deadlines, summarisation, and export. Some overlap exists among get_year_budget, check_ledger, and summarise_plan, since all can surface budget or ledger issues, but their primary intents are different enough that an agent should usually choose correctly.
All tool names use snake_case with a consistent verb_noun or verb_object pattern: get_holiday_windows, calculate_leave_cost, find_bridge_days, upsert_trip, check_ledger, list_deadlines, summarise_plan, export_ics. The only minor variation is export_ics being noun-oriented rather than verb_noun, but it still fits the convention and is unambiguous.
Nine tools is well-scoped for a holiday/leave planning server. Each tool covers a distinct part of the workflow, and there is no obvious bloat or missing core capability that would require several extra tools.
The surface covers the main lifecycle: holiday windows, leave cost, bridge days, budget, trip upsert, validation, deadlines, summary, and calendar export. The main gap is the absence of an explicit delete_trip or remove operation, though upsert_trip may allow updates and agents can likely work around this for most planning tasks.
Family calendar MCP server: read the family's week and propose changes a parent approves.
MCP server for public_holidays_mcp
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
