Kalender Sync

Creates an event in one of the calendars this access may write to.

Availability in the requested slot is checked LIVE (not from cache). An overlapping event does NOT prevent creation — the event is created regardless and the overlap comes back as a warning. Pass that warning on to the user instead of silently double-booking; whether the overlap is intended is the user's call.

The check counts only events that BLOCK the time (blocks_time: true in get_availability). Entries that do not block it — holidays, birthdays, and every all-day event from Apple/iCloud — are deliberately not reported as conflicts, because otherwise every booking on a day carrying a holiday would look like a clash. So no warning does NOT mean the day is empty: an all-day "Baustelle Darmstadt" is a working day that will not show up here. When the user asks to book on a specific day, check the day with get_availability first and mention what is already on it.

All-day events: pass bare dates (start: "2026-09-01", end: "2026-09-03") or set all_day: true. For all-day the end date is INCLUSIVE — that example creates a three-day event covering 1–3 September. Both ends must use the same form.

calendar_id is only needed when several calendars are writable; with exactly one, that one is used. list_calendars shows the writable calendars. title is required.

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

Deletes an event. The deletion is executed at the provider and propagates into any mirrored calendars through the normal sync.

Addressable are events THIS access created, and — where the user allowed managing (manageable: true in list_calendars) — any other event in that calendar.

Deleting is the irreversible one: confirm with the user first when the event is not one this access created, and say what it is (title and time) so they can recognise it. When the event has other participants, deleting it as the organiser cancels it for them too — mention that before doing it.

The same four refusals as update_event apply, each naming the way forward. For an invitation someone else organised, respond_to_event is the right tool: deleting it would only hide it locally and leave the organiser expecting the user.

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

Returns the user's busy times in a given range, across all calendars shared with this access.

How the answer is produced: every shared calendar is read directly at the provider and the results are merged. There is no detour through a copy. as_of per calendar says when it was read — reads are reused for up to 60 seconds, so an event created moments ago may briefly be missing.

What busy contains: every event in the range, including all-day events and ones marked "tentative". Cancelled events are not included.

blocks_time per entry says whether it actually occupies the time. It is false for entries that do not make the user unavailable — holidays, birthdays, and (importantly) ALL all-day events from Apple/iCloud, which that provider always marks as free with no setting for the user to change. Such an entry is still a real appointment: an all-day "Baustelle Darmstadt" is a working day, not free time.

Use it accordingly: for "am I free / find me a slot", count only blocks_time: true. For "what do I have on", list everything and let the user judge. Never present a blocks_time: false entry as nonexistent.

Completeness: the answer covers exactly the calendars the user shared — not necessarily all calendars they own. If one of them could not be read, it appears with read: false in sources and additionally in warnings. These limitations belong in your answer to the user.

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

Lists the calendars shared with this access, each with the detail level the user allowed. This tool costs no credits and works even at zero balance. Credit warnings concern the other calendar tools, not this calendar list.

readable: false means this calendar cannot be read right now — its events are also missing from get_availability. Such calendars are deliberately listed rather than omitted.

writable: true means this access may create events there. When more than one calendar is writable, create_event requires the calendar_id of one of them.

notice, when present, describes something the USER can change — either about this access or about their Kalender Sync setup. Pass it on rather than concluding the product cannot do what was asked. When it reads as an offer rather than an answer to what was asked, use your judgement about whether it fits the moment.

sync_health describes Kalender Sync's OWN synchronisation of this calendar, if it takes part in one. It does not affect availability answers (those read the provider directly), but a broken sync is something the user can fix.

Accepts, declines or tentatively accepts an invitation someone else sent the user. The organiser is notified — that is the point: removing an invitation from the calendar without answering leaves them expecting the user.

The event_id comes from get_availability, for a calendar the user allowed managing (manageable: true in list_calendars).

Everything needed is in the get_availability or search_events result — pass event_id AND calendar_id straight back, and read is_recurring and is_organizer from the same entry instead of asking the user about them.

When is_recurring is true, set scope: "occurrence" answers only that date, "series" answers all of them. If the user named a date ("on Tuesday"), that IS "occurrence" — do not ask. Ask only when they named none, because declining one date and declining a standing commitment are different messages to the organiser.

Refusals name the way forward; pass them on rather than retrying.

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

Finds events by text across the calendars shared with this access — case-insensitive substring match on title, location and description.

The search only sees what this access may see: it filters the same visibility-rendered data get_availability returns. Calendars limited to free/busy expose no text and therefore can never match — when such calendars are part of this access, a warning says so. "No match" is thus NOT proof that no such event exists.

A match in a calendar the user allowed managing carries event_id, calendar_id, is_organizer and is_recurring — everything update_event, delete_event and respond_to_event need. Act on those directly instead of calling get_availability again for the same appointment.

The range works like get_availability (single span of at most 92 days, lookback bounded to one year). Without from/to the search covers the last 7 days plus the next 85. Cancelled events are not searchable.

Matches include events that do not block time (blocks_time: false) — notably every all-day event from Apple/iCloud. They are ordinary appointments and belong in the answer; do not filter them out when the user asked what is in their calendar.

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.

Stores a feedback message from the user and notifies the Kalender Sync team, who read it. Use it when the user wanted something the other tools in this connection cannot do, or when something looks broken. It does not change anything in the user's calendars and does not fix the problem itself; it returns a feedback_id as receipt. The notification email cannot be recalled after sending. At most 5 messages per account in 24 hours.

Call this ONLY when the user explicitly asked to send feedback, or clearly agreed after you offered it. Never send feedback on your own initiative, and never include calendar content the user did not put into the message themselves.

contact_ok records whether the user agrees to be contacted about this feedback. It is consent, not a promise of a reply. Default: false for every category, including bug. Set it to true ONLY if the user explicitly agreed to be contacted about this feedback. It never subscribes the user to a newsletter.

Updates an event. title, start and end describe the complete new state — including whether it is all-day: an event created all-day becomes a timed event if this call passes timestamps, and vice versa.

Two kinds of event are addressable:

1. Events THIS access created (via event_id from create_event) — always.

2. Any other event in a calendar the user allowed managing, visible in list_calendars as manageable: true. Their ids come from get_availability.

Four things are refused, and each says what to do instead — pass that on rather than retrying: • the calendar is not released for managing (the user can allow it per calendar) • it is shared at less than full detail (a setting, not a temporary error) • the event is a synchronised COPY — change the original in the named source calendar, the change reaches this one by itself • someone else organises it — call respond_to_event with response: "declined" and the same event_id instead

Check status first: credits_exhausted means this call was NOT performed. Only warnings and credit information are returned in that case; no result data or write confirmation. Tell the user how to restore credits; do not retry automatically.