calendar-mcp

Overview Schema Source Related Servers Discussions Admin

Find a mutual slot and schedule

schedule_mutual

Finds the earliest common free slot for all attendees within a time window and schedules the meeting, respecting working hours and preferences.

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. Refuses to book if any attendee or organizer availability is unknown. 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.7/5.0

Behavior5/5

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

Beyond the annotations (write, open-world, non-idempotent), the description discloses refusal conditions, failure modes, the default preference-respecting behavior (working hours, lunch, buffer), the narrowing-only semantics of working_hours_start/end, and the send_notifications default. This is rich behavioral context an agent could not infer from the structured fields.

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?

The core action is front-loaded in the first sentence, then behavior, then a well-organized Args list. It is somewhat long, and a few Args lines (duration_minutes, summary) are near-tautological, but they are justified by the 0% schema coverage. Structure is clear and nothing important is buried.

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?

With an output schema present, return values needn't be described. Given 13 parameters, a composite read-then-write flow, and non-idempotent writes, the description supplies everything needed: parameter meanings, preconditions, failure handling, and sibling references. Nothing material is missing for correct invocation.

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, and it does: every one of the 13 parameters is explained in the Args block, including format details ('HH:MM' local, ISO 8601 with UTC offset) and semantic nuances (working hours narrow but never widen; account from 'calendar-mcp accounts').

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 composite verb ('Find the first slot... then book the meeting there'), naming both the search and the booking resource. This combined behavior inherently distinguishes it from pure-query siblings like query_free_busy and pure-write siblings like create_event. An agent can tell what it does without opening the schema.

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?

It gives strong scenario guidance: it refuses to book when availability is unknown, fails when no common slot exists, and tells the agent to widen the window or shorten the meeting. It also references get_preferences as the source of saved settings. What it lacks is an explicit 'use X instead when Y' against named siblings, so it stops short of 5.

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