Google Calendar Integration

Quick Start: Create Event

GOOGLECALENDAR_CREATE_EVENT
  summary: "[TITLE]"
  start_time: "YYYY-MM-DDTHH:MM:SS"
  end_time: "YYYY-MM-DDTHH:MM:SS"
  timezone: "[IANA_TIMEZONE]"
  attendees: ["[EMAIL]"]

Critical Rules

1. PATCH/UPDATE Requires Both Times

Always send both start_time AND end_time when patching. Single-field patches cause timezone interpretation bugs.

GOOGLECALENDAR_PATCH_EVENT
  event_id: "[EVENT_ID]"
  calendar_id: "primary"
  start_time: "YYYY-MM-DDTHH:MM:SS"   # Always include
  end_time: "YYYY-MM-DDTHH:MM:SS"     # Always include
  timezone: "[IANA_TIMEZONE]"          # Always include

2. Always Specify Timezone

Never omit the timezone parameter. Without it, times are interpreted as UTC, causing events to land at wrong times.

3. Reuse IDs from Prior Tool Calls

Never fabricate IDs. Always use exact values returned from previous tool calls:

• •connectionId - from search_connections result
• •event_id - from GOOGLECALENDAR_FIND_EVENT result
• •toolName - exact spelling from connection's tool list (e.g., GOOGLECALENDAR_UPDATE_EVENT, not GOOGLE_CALENDAR_UPDATE_EVENT)

4. Verify Day-of-Week Matches Date

When scheduling involves a day name (e.g., "next Monday", "this Friday"):

1. •Calculate the target date from the day name
2. •Verify the calculated date's day-of-week matches what user requested
3. •State both day AND date when confirming with user (e.g., "Monday, January 27")

Timezone Reference

Common Abbreviations to IANA Names

Timezone Conversion

To convert between timezones:

1. •Find UTC offset for source timezone (from table above)
2. •Find UTC offset for target timezone
3. •Calculate difference: target_offset - source_offset
4. •Add difference to the time

Examples:

Quick mental model:

• •Negative offset = behind UTC (Americas)
• •Positive offset = ahead of UTC (Europe, Asia, Pacific)
• •Moving east (toward positive) = add hours
• •Moving west (toward negative) = subtract hours

Situational Handling

Change duration ("make it 30 minutes")

1. •Get current event if needed: GOOGLECALENDAR_FIND_EVENT
2. •Patch with BOTH times:
   • •start_time: keep original
   • •end_time: calculate new (start + new duration)
   • •timezone: user's timezone (IANA format)

Reschedule to new time

1. •If day name given, verify day-of-week matches calculated date
2. •Convert requested time to user's timezone if cross-timezone
3. •Patch with BOTH times:
   • •start_time: new time
   • •end_time: new time + original duration
   • •timezone: user's timezone (IANA format)

Create for Zoom meeting

GOOGLECALENDAR_CREATE_EVENT
  summary: "[ZOOM_TOPIC]"
  start_time: "YYYY-MM-DDTHH:MM:SS"
  end_time: "YYYY-MM-DDTHH:MM:SS"
  timezone: "[IANA_TIMEZONE]"
  attendees: ["[EMAIL]"]
  location: "[ZOOM_JOIN_URL]"
  description: "Join Zoom: [ZOOM_JOIN_URL]"

Date/Time Format

Use ISO 8601 WITHOUT offset. Let timezone param handle it:

{
  "start_time": "YYYY-MM-DDTHH:MM:SS",
  "end_time": "YYYY-MM-DDTHH:MM:SS",
  "timezone": "[IANA_TIMEZONE]"
}

Never use Z suffix or offset like -10:00 in the time string.

Error Recovery

Example: The "time range is empty" Bug

Wrong (only end_time):

{
  "end_time": "YYYY-MM-DDTHH:MM:SS",
  "timezone": "[IANA_TIMEZONE]"
}

API interprets end as UTC while start stays in local time. End appears before start.

Right (both times):

{
  "start_time": "YYYY-MM-DDTHH:MM:SS",
  "end_time": "YYYY-MM-DDTHH:MM:SS",
  "timezone": "[IANA_TIMEZONE]"
}

Anti-Patterns