Tool: suggest_time
Suggests time periods across one or more calendars. To access the primary calendar, add 'primary' in the attendee_emails field.
Use this tool for queries like:
- When are all of us free for a meeting?
- Find a 30 minute slot where we are both available.
- Check if jane.doe@google.com is free on Monday morning.
Example:
suggest_time(
attendee_emails=['joedoe@gmail.com', 'janedoe@gmail.com'],
start_time='2024-09-10T00:00:00',
end_time='2024-09-17T00:00:00',
duration_minutes=60,
preferences={
'start_hour': '09:00',
'end_hour': '17:00',
'exclude_weekends': True
}
)
# Returns up to 5 suggested time slots where both users are available for at least one hour between 9:00 AM and 5:00 PM on weekdays from September 10 through September 16, 2024.
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 (
|
attendeeEmails[]
string
Required. The attendee emails to find free time for.
startTime
string
Required. The start of the interval for the query formatted as per ISO 8601.
endTime
string
Required. The end of the interval for the query formatted as per ISO 8601.
Union field _time_zone
.
_time_zone
can be only one of the following:
timeZone
string
Optional. Time zone used for the time values. This field accepts IANA Time Zone database names, e.g., America/Los_Angeles
. The default is the time zone of the user's primary calendar.
Union field _duration_minutes
.
_duration_minutes
can be only one of the following:
durationMinutes
integer
Optional. Minimum duration of a free time slot in minutes. The default is 30 minutes.
Union field _preferences
.
_preferences
can be only one of the following:
preferences
object (
Preferences
)
The preferences to find suggested time for.
Preferences
| JSON representation |
|---|
{ "startHour" : string "endHour" : string "excludeWeekends" : boolean "pageSize" : integer } |
Union field _start_hour
.
_start_hour
can be only one of the following:
startHour
string
The preferred start hour of day (e.g., 09:00
).
Union field _end_hour
.
_end_hour
can be only one of the following:
endHour
string
The preferred end hour of day (e.g., 17:00
).
Union field _exclude_weekends
.
_exclude_weekends
can be only one of the following:
excludeWeekends
boolean
Whether to exclude weekends.
Union field _page_size
.
_page_size
can be only one of the following:
pageSize
integer
Maximum number of time slots to return. Default is 5.
Output Schema
Response message for SuggestTime.
SuggestTimeResponse
| JSON representation |
|---|
{
"timeSlots"
:
[
{
object (
|
| Fields | |
|---|---|
timeSlots[]
|
List of suggested time slots. |
TimeSlot
| JSON representation |
|---|
{ "startTime" : string , "endTime" : string , "durationMinutes" : integer } |
| Fields | |
|---|---|
startTime
|
The start time of the free time slot as an ISO 8601 formatted timestamp. |
endTime
|
The end time of the free time slot as an ISO 8601 formatted timestamp. |
durationMinutes
|
The duration of the free time slot in minutes. |
Tool Annotations
Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌
