calendar

name	calendar
description	Read, create, update and delete Google Calendar events. Requires Google OAuth. Tools: http.

Google Calendar Skill

Read, create, update, move and delete appointments via the Google Calendar API.

Tool: http

All requests require auth_provider: "google".

Base URL: https://www.googleapis.com/calendar/v3

Fetch today's/upcoming events

{
  "method": "GET",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin={ISO_DATE_NOW}&maxResults=10&singleEvents=true&orderBy=startTime",
  "auth_provider": "google"
}

Example for timeMin: 2024-01-15T00:00:00Z (ISO 8601 UTC)

Events for a specific time range

{
  "method": "GET",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin={START}&timeMax={END}&singleEvents=true&orderBy=startTime",
  "auth_provider": "google"
}

Create an event

{
  "method": "POST",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  "auth_provider": "google",
  "body": {
    "summary": "{TITLE}",
    "start": {
      "dateTime": "{ISO_START}",
      "timeZone": "Europe/Vienna"
    },
    "end": {
      "dateTime": "{ISO_END}",
      "timeZone": "Europe/Vienna"
    },
    "description": "{DESCRIPTION}"
  }
}

Update an event (partial – PATCH)

Use PATCH to change only specific fields of an existing event. You need the eventId from a previous GET request.

{
  "method": "PATCH",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}",
  "auth_provider": "google",
  "body": {
    "summary": "{NEW_TITLE}",
    "start": {
      "dateTime": "{NEW_ISO_START}",
      "timeZone": "Europe/Vienna"
    },
    "end": {
      "dateTime": "{NEW_ISO_END}",
      "timeZone": "Europe/Vienna"
    },
    "description": "{NEW_DESCRIPTION}",
    "location": "{NEW_LOCATION}"
  }
}

Only include the fields you want to change – omitted fields stay unchanged.

Updatable fields:

• summary – title
• description – notes / description
• start / end – date and time (both must be provided together)
• location – place
• colorId – color label (string "1" through "11")
• reminders – reminder overrides
• attendees – list of attendees (email addresses)

Move an event (change time)

Moving an event to a different time is just a PATCH with new start and end:

{
  "method": "PATCH",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}",
  "auth_provider": "google",
  "body": {
    "start": {
      "dateTime": "{NEW_ISO_START}",
      "timeZone": "Europe/Vienna"
    },
    "end": {
      "dateTime": "{NEW_ISO_END}",
      "timeZone": "Europe/Vienna"
    }
  }
}

Move an event to another calendar

{
  "method": "POST",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}/move?destination={TARGET_CALENDAR_ID}",
  "auth_provider": "google"
}

Delete an event

{
  "method": "DELETE",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}",
  "auth_provider": "google"
}

Returns HTTP 204 (no body) on success.

Finding the eventId

To update, move or delete an event you need its eventId. Get it by fetching events first:

1. Fetch events with GET (see above)
2. Each event in items[] has an id field – that is the eventId
3. Match the correct event by summary, start.dateTime or other fields

Important: Always fetch events first and confirm the correct event with the user before modifying or deleting it.

Generating ISO dates

Use the datetime tool with output_format parameter to generate ISO date/datetime strings directly.

Available output formats:

• "iso_date" - YYYY-MM-DD (date only)
• "iso_datetime" - YYYY-MM-DDTHH:mm:ss with timezone offset (e.g. 2024-01-15T14:00:00+01:00)
• "iso_datetime_utc" - YYYY-MM-DDTHH:mm:ssZ (UTC, e.g. 2024-01-15T14:00:00Z)
• "iso_datetime_utc_ms" - YYYY-MM-DDTHH:mm:ss.SSSZ (UTC with milliseconds, e.g. 2024-01-15T14:00:00.000Z)

Examples:

• "Today at 2 PM" → datetime absolute with base: "today", time: "14:00", output_format: "iso_datetime" → returns 2024-01-15T14:00:00+01:00
• "Tomorrow at 9:00" → datetime absolute with base: "tomorrow", time: "09:00", output_format: "iso_datetime_utc" → returns 2024-01-16T09:00:00Z
• "On March 15 at 2 PM" → datetime absolute with base: "2024-03-15", time: "14:00", output_format: "iso_datetime" → returns 2024-03-15T14:00:00+01:00
• For timeMin queries: Use datetime now with output_format: "iso_datetime_utc" → returns 2024-01-15T00:00:00Z
• Germany/Central Europe: timezone is Europe/Berlin (UTC+1 / UTC+2 in summer). Use iso_datetime for local timezone or iso_datetime_utc for UTC.

Note: The base parameter accepts enum values ("today", "tomorrow", etc.), Unix timestamps (number), or ISO date/datetime strings ("2024-03-15", "2024-03-15T14:00:00", etc.).

Workflows

Read events aloud

1. Fetch events (timeMin = now)
2. Parse response: items[].summary, items[].start.dateTime
3. Read aloud with tts: "You have a meeting at 2 PM with..."

Move an event to a different time

1. datetime: now → current time (Unix timestamp in milliseconds)
2. Fetch events with GET to find the target event
3. Identify the correct event by name/time → extract id
4. Calculate the new start/end timestamps
5. PATCH the event with new start and end
6. Confirm to user via tts: "Your meeting has been moved to 3 PM"

Update event details

1. Fetch events to find the target event → extract id
2. PATCH the event with the changed fields (e.g. new title, description, location)
3. Confirm to user via tts

Delete an event

1. Fetch events to find the target event → extract id
2. Confirm with the user which event to delete
3. DELETE the event
4. Confirm to user via tts: "The event has been deleted"

Reschedule by a relative amount ("push meeting 1 hour later")

1. datetime: now → current time (Unix timestamp in milliseconds)
2. Fetch the event to get current start.dateTime and end.dateTime
3. Add the offset (e.g. +1 hour) to both start and end
4. PATCH with the new times
5. Confirm via tts

Examples

• "What do I have today?" → Fetch today's events + TTS
• "What is my next appointment?" → maxResults=1 + TTS
• "Create an appointment tomorrow at 10 AM" → POST event
• "Am I free next Monday?" → Fetch events for that day
• "Move the 2 PM meeting to 4 PM" → GET events, find it, PATCH with new time
• "Push my next meeting back by 30 minutes" → GET event, add 30 min, PATCH
• "Rename my dentist appointment to doctor" → GET events, PATCH summary
• "Change the location of the team meeting to Room 5" → GET events, PATCH location
• "Delete the meeting at 3 PM" → GET events, find it, DELETE
• "Cancel tomorrow's breakfast meeting" → GET tomorrow's events, DELETE