create_event

This reference is generated from the published tool contract.

Behavior and boundaries

Creates one standalone event without guests in a writable Google, Microsoft or CalDAV calendar. Bounded weekly series are supported only for Google and Microsoft; CalDAV series must be created in the calendar app. For a series provide recurrence with frequency weekly, count (2–104 total occurrences including the first), and optional interval (weeks, default 1); the last occurrence must be within 104 weeks. The series repeats on the weekday and local clock time of start in timeZone. start and end must be on the same local day for a series and must not cross or lie inside a local clock change. Confirm the requested repetition and total count with the user before creating a series; do not invent them. requestId identifies the entire series and must be reused unchanged on retries. start and end must include UTC offsets; timeZone must be IANA. For an all-day event in Google, Microsoft or CalDAV, set allDay to true and give startDate and endDate as YYYY-MM-DD instead of start and end; endDate is the last day and is included, so 27 to 29 October is startDate 2026-10-27 and endDate 2026-10-29. Omit endDate for a one-day event. An all-day event spans at most 366 days and cannot be a series. timeZone is still required; it never shifts the dates. update_event cannot change the date of an all-day event. This tool never sends invitations. update_event and delete_event change standalone events and single occurrences of your own series without guests; update_event can also rename an entire series.

Permissions

Granted scopes, accounts, calendars and visibility rules limit access. Workspace administrators do not automatically gain access to other users’ accounts.

calendar:read, calendar:write

Consent and boundaries

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "calendarId": {
      "type": "string",
      "minLength": 1
    },
    "requestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "recurrence": {
      "type": "object",
      "properties": {
        "frequency": {
          "type": "string",
          "const": "weekly"
        },
        "interval": {
          "type": "integer",
          "minimum": 1,
          "maximum": 104
        },
        "count": {
          "type": "integer",
          "minimum": 2,
          "maximum": 104
        }
      },
      "required": [
        "frequency",
        "count"
      ],
      "additionalProperties": false
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "description": {
      "type": "string",
      "maxLength": 10000
    },
    "location": {
      "type": "string",
      "maxLength": 1000
    },
    "start": {
      "description": "Timed events only: start with UTC offset. Omit when allDay is true.",
      "type": "string"
    },
    "end": {
      "description": "Timed events only: end with UTC offset. Omit when allDay is true.",
      "type": "string"
    },
    "timeZone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "freeBusyStatus": {
      "type": "string",
      "enum": [
        "free",
        "busy"
      ]
    },
    "allDay": {
      "description": "true for an all-day event; then use startDate and endDate instead of start and end.",
      "type": "boolean"
    },
    "startDate": {
      "description": "All-day events only: first day as YYYY-MM-DD.",
      "type": "string"
    },
    "endDate": {
      "description": "All-day events only: last day as YYYY-MM-DD, included. Omit for a one-day event.",
      "type": "string"
    }
  },
  "required": [
    "calendarId",
    "requestId",
    "title",
    "timeZone"
  ],
  "additionalProperties": false
}

Output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "eventId": {
      "type": "string"
    },
    "idempotentReplay": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "idempotencyStatus": {
      "type": "string",
      "enum": [
        "created",
        "replayed",
        "provider_managed"
      ]
    }
  },
  "required": [
    "ok",
    "eventId",
    "idempotentReplay",
    "idempotencyStatus"
  ],
  "additionalProperties": false
}

Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the current resource or send status first.

Error handling