calendar-mcp

Overview Schema Source Related Servers Discussions Admin

Find a mutual slot and schedule

schedule_mutual

Find the earliest overlapping free slot across attendees' calendars and book a meeting with everyone invited. Respects working hours and buffers; errors if no common slot exists.

Instructions

Find the first slot where everyone is free, then book the meeting there.

Reads each attendee's free/busy inside the window, picks the earliest gap that fits duration_minutes, and creates the event with all of them invited. Fails with an error if no common slot exists -- widen the window or shorten the meeting and try again.

By default the search obeys the user's own settings from get_preferences: their working hours per weekday (so nothing lands on a day off), their lunch break, and the buffer they want around meetings. working_hours_start and working_hours_end narrow that further; they never widen it.

Args: attendee_calendar_ids: Attendee email addresses whose availability matters. time_min: Earliest the meeting may start, ISO 8601 with a UTC offset. time_max: Latest the meeting may end, ISO 8601 with a UTC offset. duration_minutes: Length of the meeting in minutes. summary: Title for the meeting. description: Optional agenda or notes. location: Optional location or meeting link. organizer_calendar_id: Calendar the meeting is created on. working_hours_start: Optional daily earliest start, 'HH:MM' local to the calendar, e.g. '09:00'. working_hours_end: Optional daily latest end, 'HH:MM', e.g. '17:00'. send_notifications: Whether Google emails the attendees. Default true. respect_preferences: Obey the user's saved working hours, lunch and buffer. Set false to search the whole window instead. account: Account name from 'calendar-mcp accounts'; omit for the default.

Input Schema

TableJSON Schema

Name	Required	Default
`account`	No
`summary`	Yes
`location`	No
`time_max`	Yes
`time_min`	Yes
`description`	No
`duration_minutes`	Yes
`working_hours_end`	No
`send_notifications`	No
`respect_preferences`	No
`working_hours_start`	No
`attendee_calendar_ids`	Yes
`organizer_calendar_id`	No	primary

Output Schema

TableJSON Schema

Name	Required	Description
`event`	Yes	The event after the operation.
`message`	No	One-line human-readable summary of what happened.
`calendar_id`	Yes	Calendar the event lives on.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Sep 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The annotations already indicate this is a write operation (readOnlyHint=false), but the description adds valuable behavioral detail: it reads free/busy, creates an event inviting everyone, fails when no slot exists, respects saved preferences, and lets working_hours_start/end only narrow the window. This goes well beyond the structured annotations.

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

Conciseness5/5

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

The description is front-loaded with a one-sentence summary, then a compact behavioral paragraph, then a structured Args list. Every sentence earns its place, and the length is justified by the number of parameters and the nuanced preference behavior.

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

Completeness5/5

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

Given the tool's complexity (availability search plus booking), the description covers the algorithm, inputs, defaults, failure mode, and edge-case behavior. An output schema exists, so the lack of return-value detail is acceptable, and nothing critical is missing for an agent to invoke the tool correctly.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden of explaining all 13 parameters. It does so thoroughly: ISO 8601 format for time bounds, plain-language meaning for each parameter, defaults, units for duration, and subtle semantics like 'narrow that further; they never widen it' and 'Set false to search the whole window instead.'

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?

The description states a specific verb+resource: find a free slot for everyone and book the meeting there. It also clearly explains the algorithm (reads availability, picks earliest gap, creates event) and thereby distinguishes itself from sibling tools like find_focus_time, create_event, and query_free_busy.

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 description gives clear context for when to use the tool: when you need to find a mutual slot and schedule a meeting in one step. It also provides failure guidance and notes preference options, but it does not explicitly name alternatives or state when-not-to-use this tool versus a specific sibling.

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