Calendar Search Events
calendar_search_eventsSearch a Google Calendar for events in a time window using presets or explicit start/end times. Returns compact event details, count, and pagination for scheduling and availability checks.
Instructions
Find events on one calendar in a time window, given as a range_preset or explicit time_min/time_max. For the user's upcoming week plus pending invitations use calendar_get_calendar_digest, and for full details of known events use calendar_read_events. Returns compact events (id, title, start and end in the account time zone, all_day, status, organizer, my_response, requires_response, meeting_url, location, is_recurring, updated_at), count, next_page_token, account_timezone and the effective_time_min/effective_time_max that were applied.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "calendar_search_events"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order_by | No | 'startTime' sorts by start (applied only when single_events is true; otherwise no order is requested) or 'updated' sorts by last modification time. | startTime |
| time_max | No | RFC3339 time with offset, e.g. '2026-03-08T00:00:00Z'; returns events that start before it. Overrides the end of range_preset. | |
| time_min | No | RFC3339 time with offset, e.g. '2026-03-01T00:00:00Z'; returns events that end after it. Overrides the start of range_preset; with no time_min, time_max or range_preset the list is unbounded and starts at the calendar's oldest events. | |
| page_token | No | The next_page_token from the previous response of this same call; omit for the first page. Keep every other argument the same; range_preset 'next_7_days' moves with the clock, so page with the effective_time_min/effective_time_max of the first response. | |
| calendar_id | No | Calendar ID: 'primary' for the user's main calendar, or an ID from calendar_get_calendar_context's calendars (often an email address). | primary |
| max_results | No | Maximum events per page, 1 to 2500; next_page_token continues the list. | |
| range_preset | No | Window in the account's time zone: 'today' or 'tomorrow' (midnight to midnight), 'this_week' (Monday 00:00 for 7 days) or 'next_7_days' (from now). Fills only the bound that time_min or time_max leaves unset. | |
| single_events | No | True expands recurring events into their individual occurrences (instance IDs). False returns each series once, as its master event. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of items in this response. | |
| events | No | ||
| has_more | No | Whether another page is available. | |
| fetched_at | No | RFC3339 time when this response was fetched. | |
| range_preset | No | ||
| next_page_token | No | Opaque token for the next page, or null. | |
| account_timezone | No | ||
| effective_time_max | No | ||
| effective_time_min | No |