Skip to main content

Outlook Calendar

View as Markdown

Exposes the Microsoft Graph calendar API as agent tools: list/read events (including calendarView expansion of recurring series), create/update/delete events, respond to invitations, find meeting times, get free/busy schedules, list/create calendars, and delta-sync a calendar view. Operates on the acting user's calendar.

What it does​

An agent-invocable tool node — no data flows through lanes. Each operation is a @tool_function an agent calls on demand. Operational targets (event id, calendar id) are always tool-call parameters, never node config. Outputs are cleaned shapes (id, subject, start, end, location, organizer, attendees, isAllDay, isCancelled, seriesMasterId, recurrence, onlineMeeting, webLink, bodyPreview for events; id, name, isDefaultCalendar, canEdit, owner for calendars), not raw Graph JSON.

Configuration​

FieldNotes
microsoft.authTypeservice (Entra app, client credentials) or user (OAuth).
microsoft.tenantId / microsoft.clientId / microsoft.clientSecretEntra app credentials for service auth.
microsoft.userPrincipalNameActing user's UPN for service auth (app-only calls target /users/{upn}).
microsoft.oAuthButton / microsoft.userTokenUser OAuth: sign in to populate the access token.
outlook_calendar.accessreadonly or write (default). Resolved by the shared OUTLOOK_CALENDAR spec in core/microsoft_access.py; scopes are never hand-entered.

Access tiers → scopes​

TierScopeCapability
readonlyCalendars.Readlist/read events and calendars, find meeting times, get schedules, and delta-sync only
writeCalendars.ReadWritefull read/write (default) — create/update/delete events, respond to invitations, and create calendars, plus everything readonly grants

No gate flags — unlike Outlook Mail's hard-delete flag, event deletion here needs only the write tier.

Tools​

  • Read: outlook_calendar_list_events (calendarView, recurring series expanded), outlook_calendar_get_event, outlook_calendar_find_meeting_times, outlook_calendar_get_schedule, outlook_calendar_list_calendars, outlook_calendar_delta_sync.
  • Write: outlook_calendar_create_event, outlook_calendar_update_event (PATCH — only provided fields change), outlook_calendar_delete_event, outlook_calendar_respond (accept/decline/tentativelyAccept), outlook_calendar_create_calendar.
  • Diagnostics: outlook_calendar_check_connection verifies that granted OAuth scopes cover the configured access tier.

Setup​

Authenticate with either an Entra app (microsoft.tenantId / microsoft.clientId / microsoft.clientSecret / microsoft.userPrincipalName, client-credentials flow) or user OAuth (click sign-in to populate microsoft.userToken). See microsoft-oauth.md for the Entra app / consent setup shared by every Microsoft 365 tool service. The app must be granted the Graph Calendars.Read and/or Calendars.ReadWrite permission (application or delegated, matching the auth mode and the configured tier) with admin consent.

Limits​

  • outlook_calendar_create_event / outlook_calendar_update_event accept start/end as either a plain 'YYYY-MM-DDTHH:MM:SS' string (wrapped as UTC) or an already-shaped {dateTime, timeZone} object.
  • attendees invites are sent by Graph itself as part of creating/updating the event — the write tier gates the Graph call, not a separate "send" step.
  • outlook_calendar_find_meeting_times (findMeetingTimes) needs a delegated (signed-in user) context on Microsoft's side and may not be supported under app-only (client-credentials) authentication.
  • outlook_calendar_delta_sync takes start/end on the first call; pass the returned delta_link back in on subsequent calls to fetch only what changed.
  • Rate limits are per Entra app / tenant; the node retries 429/5xx with exponential backoff.

Examples​

An agent creates a meeting and later syncs changes:

outlook_calendar_create_event { "subject": "Sync", "start": "2026-08-11T14:00:00",
                                 "end": "2026-08-11T14:30:00",
                                 "attendees": ["alex@contoso.com"] }
outlook_calendar_delta_sync   { "start": "2026-08-01T00:00:00", "end": "2026-08-08T00:00:00" }
outlook_calendar_delta_sync   { "delta_link": "<deltaLink from the previous call>" }

Upstream docs​

Troubleshooting​

  • Scope / 403 errors: call outlook_calendar_check_connection; if scopes are missing, disconnect and reconnect the Microsoft account (user auth) or grant/consent the Entra app permission (service auth) at the required tier.
  • access is readonly: every write tool raises MicrosoftAccessError; raise outlook_calendar.access to write.
  • outlook_calendar_find_meeting_times fails under app-only auth: this endpoint needs a delegated (signed-in user) context; switch to user OAuth or use outlook_calendar_get_schedule instead.
Last updated on