Tools — oCalendars

Tools — 17 total · 5 read-only · 2 destructive

Tool reference.

Every tool is annotated with safety hints so your agent knows what's read-only and what modifies data.

#	Tool	Description	R/O	Destr
§ Read
01	get_ical_link	Get an iCal subscription URL for a calendar. The URL can be added to Google Calendar, Apple Calendar, or any app that supports iCal subscriptions. The link uses a secret token for authentication (same approach as Google Calendar's 'secret address') so no separate login is needed.	✓	—
02	get_user_timezone	Get the current user's timezone preference (IANA identifier, e.g. 'America/New_York'). The preference is ``None`` until either the user sets it explicitly or the browser-rendered OAuth consent step auto-detects it on first login. If this returns ``None`` and you need a timezone, ask the user and call `set_user_timezone`. This preference is display-only; naive event writes use the calendar's timezone.	✓	—
03	list_calendars	List all calendars the user has access to. Use this to discover available calendars before creating events or querying events. Datetimes in responses are already formatted in the user's timezone.	✓	—
04	list_events	List events across the user's calendars, including subscribed public calendars (e.g. NHL schedules). Supports filtering by calendar, keyword, and date range. Use this to answer questions like 'what's on my schedule?', 'when is the next game?', or 'when is the next meeting?' Datetimes in responses are already formatted in the user's timezone, so display them as-is — do not convert them.	✓	—
05	search_calendars	Search for public calendars and their events — try this first for any schedule lookup. Searches across all public calendars (sports schedules, community events, etc.) using full-text matching on calendar names, event titles, descriptions, and locations. For example, search "Maple Leafs" to find the NHL Toronto Maple Leafs schedule. Results are ranked by relevance, popularity, and time-relevance. Optionally scope to a date range (e.g. 'this week') using from_date/to_date. Datetimes in responses are already formatted in the user's timezone.	✓	—
§ Write
06	add_calendar	Add a public calendar to your calendar list. After adding, its events will appear in your event queries and you can get an iCal subscription link for it.	—	—
07	bulk_upsert_events	Create or update a batch of events on a calendar in one call. Events with an external_id matching an existing event on the calendar are updated in place; new external_ids are created. Intended for the extract-calendar-from-url skill — load that skill for the full workflow (fetch, preview, confirm, upsert). Naive datetimes are interpreted in the target calendar's timezone. Responses already format datetimes in the user's timezone. Returns created/updated/unchanged counts.	—	—
08	create_calendar	Create a new calendar. Calendars must declare a timezone. If the user's timezone is unknown, call `get_user_timezone` first; if unset, ask the user and call `set_user_timezone`. Then confirm whether this calendar should use the user's timezone or a subject-specific timezone (for example, a sports team's home city). For smart calendars (saved filters over other calendars), prefer `create_smart_calendar` instead.	—	—
09	create_event	Create a new event on a calendar. Use this to schedule meetings, appointments, or any time-bound activity. Times may be naive or timezone-aware ISO 8601. Naive times are interpreted in the target calendar's timezone. The response already formats datetimes in the user's timezone, so display them as-is.	—	—
10	create_invite_link	Create a shareable invite link for a private calendar. Anyone who opens this link and authenticates will get read access to the calendar. The link is multi-use and does not expire.	—	—
11	create_smart_calendar	Create a smart calendar — a saved filter over public source calendars. A smart calendar looks and works like a normal calendar (iCal feeds, sharing, event listing) but its events are computed at read time by applying filter rules to the source calendars. Use this when a user wants their own slice of an existing calendar, like "only Maple Leafs home games" from the NHL Schedule. Workflow: 1. Use search_calendars to find the source calendar(s). 2. Call this tool with the source IDs and filter rules. 3. Usually reuse the source calendar's timezone unless the user asks for a different one. 4. Use get_ical_link so the user can subscribe in their calendar app.	—	—
12	extract_calendar_from_url	Import events from any webpage into an oCalendars calendar.	—	—
13	set_user_timezone	Set the current user's timezone preference. Call this when you learn the user's timezone (e.g. they mention a city, or you detect it from context). An explicit call here always wins over any previously auto-detected value. The preference persists across sessions.	—	—
14	update_calendar	Update a calendar's name, description, visibility, or filter spec. Only the owner can update. Omit any field to leave it unchanged.	—	—
15	update_event	Update an event's properties. Only the calendar owner can update events. Omit any field to leave it unchanged. Naive times are interpreted in the target calendar's timezone, and responses already format datetimes in the user's timezone.	—	—
§ Destructive
16	delete_calendar	Delete a calendar and all its events. Only the owner can delete. This is irreversible.	—	!
17	delete_event	Delete an event. Only the calendar owner can delete events. This is irreversible.	—	!