Skip to main content
Glama
mail-mcp-server

mail-mcp-server

plan_set_vacation

Plan vacation responder changes before applying them: preview on/off settings, optional dates, and affected mailboxes, then return a plan_id for execution after approval.

Instructions

Dry run: changes nothing. Returns what would be affected and a plan_id for execute_plan. Show the user the summary before asking whether to execute. Turn the vacation responder on (with its text and optional dates) or off.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mailbox": "<mailbox>",
      "enabled": "<enabled>"
    },
    "name": "plan_set_vacation"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoDate or date-time it ends
bodyNoPlain-text reply; required to turn it on
startNoDate or date-time it starts
enabledYes
mailboxYesA connected mailbox address (see list_mailboxes)
subjectNo
domain_onlyNoWorkspace mailboxes: reply only within the domain
contacts_onlyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations at all, the description carries the burden, and it does disclose the single most important trait: this is a dry run that changes nothing. It also reveals the return payload (affected items plus plan_id), which is genuinely useful given there is no output schema. It does not address permission requirements, whether a plan expires or goes stale before execution, or what happens if the responder is already in the requested state.

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

Conciseness3/5

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

Short and waste-free, but poorly front-loaded: the lead sentence describes the dry-run mechanic while the actual capability is deferred to the last sentence. An agent scanning for 'what does this do' must read past the dry-run instruction, the execute_plan handoff, and a UX directive before reaching the purpose.

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

Completeness3/5

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

An 8-parameter mutation-planning tool with no annotations and no output schema needs more from prose than this. It covers the dry-run contract and the plan_id handoff well, but leaves the two boolean targeting flags (domain_only, contacts_only) and the already-on/already-off case undiscussed, and does not say how long the plan_id stays valid.

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

Parameters4/5

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

Schema coverage is 63%, and the description partially compensates by tying the action to its payload — turning it on requires its text ('body') and accepts optional dates ('start'/'end') — which matches the schema note that body is required when enabling. It says nothing about subject, domain_only, contacts_only, or mailbox beyond what the schema documents, so a quarter of the parameters remain uninterpreted.

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 concrete verb and resource — 'Turn the vacation responder on ... or off' — and names the two things an agent needs to tell apart: this is the dry run, and this is the sibling called execute_plan. The only weakness is ordering: the actual purpose arrives in the final sentence, after the dry-run mechanics, so the agent must read the whole string to learn what is being planned.

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 explicit workflow guidance that no sibling would supply: show the user the summary, then ask whether to execute, then call execute_plan with the plan_id. That is a clear when-and-how. It stops short of an explicit exclusion (for example, that get_vacation should be used to read the current state rather than planning blind), so it is not a full 5.

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