MCP Tools Reference: calendarmcp.googleapis.com

Tool: suggest_time

Suggests time periods across one or more calendars.

The following sample demonstrate how to use curl to invoke the suggest_time MCP tool.

Curl Request 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "suggest_time",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for SuggestTime.

SuggestTimeRequest

JSON representation 
{
  "attendeeEmails": [
    string
  ],
  "startTime": string,
  "endTime": string,

  "timeZone": string

  "durationMinutes": integer

  "preferences": {
    object (Preferences)
  }
}
Fields
attendeeEmails[]

string

Required. Attendee emails to find free time for.
startTime

string

Required. Query interval start (ISO 8601).
endTime

string

Required. Query interval end (ISO 8601).

Union field _time_zone.

_time_zone can be only one of the following:
timeZone

string

Optional. Time zone for search times (IANA ID, for example Europe/Zurich). Default: the offset of start_time, if none then the user's primary time zone.

Union field _duration_minutes.

_duration_minutes can be only one of the following:
durationMinutes

integer

Optional. Min duration of free slot in minutes. Default: 30.

Union field _preferences.

_preferences can be only one of the following:
preferences

object (Preferences)

Preferences to find suggested time.

Preferences

JSON representation 
{

  "startHour": string

  "endHour": string

  "excludeWeekends": boolean

  "pageSize": integer
}
Fields

Union field _start_hour.

_start_hour can be only one of the following:
startHour

string

Preferred start hour as "HH:mm" (24-hour format).

Union field _end_hour.

_end_hour can be only one of the following:
endHour

string

Preferred end hour as "HH:mm" (24-hour format).

Union field _exclude_weekends.

_exclude_weekends can be only one of the following:
excludeWeekends

boolean

Exclude weekends.

Union field _page_size.

_page_size can be only one of the following:
pageSize

integer

Max number of slots to return. Default: 5.

Output Schema

Response message for SuggestTime.

SuggestTimeResponse

JSON representation 
{
  "timeSlots": [
    {
      object (TimeSlot)
    }
  ]
}
Fields
timeSlots[]

object (TimeSlot)

Suggested time slots.

TimeSlot

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "durationMinutes": integer,
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  }
}
Fields
startTime
(deprecated)

string

Deprecated: use start instead.
endTime
(deprecated)

string

Deprecated: use end instead.
durationMinutes
(deprecated)

integer

Deprecated: use start and end to compute duration instead.
start

object (DateOrDateTime)

The start time of the time slot.
end

object (DateOrDateTime)

The end time of the time slot.

DateOrDateTime

JSON representation 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Fields
date

string

ISO 8601 date at midnight UTC (for example, '2019-11-20T00:00:00Z').
dateTime

string

ISO 8601 timestamp (for example, '2019-11-20T08:19:06-07:00').
timeZone

string

TZDB timezone name.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌