GDPR-compliant calendar access for AI assistants: read, create, edit, RSVP. Google, MS 365, Apple.
Scored across 8 tools
Each tool targets a clearly distinct action or resource: event CRUD, availability lookup, text search, calendar listing, invitation responses, and feedback. Where purposes could blur, such as update_event versus respond_to_event, the descriptions explicitly route the agent to the correct tool.
All tool names follow a uniform snake_case verb_noun pattern: create_event, delete_event, get_availability, list_calendars, respond_to_event, search_events, send_feedback, update_event. There are no mixed conventions or vague verbs.
Eight tools is well-scoped for a calendar access server: the core event lifecycle, availability, search, calendar introspection, and response handling are all represented without unnecessary duplication. The auxiliary send_feedback tool is justified as a catch-all for unsupported requests.
The surface covers create, read, update, delete, availability, text search, and invitation responses, which covers most calendar workflows end-to-end. Minor gaps remain around explicit recurrence creation and attendee management, but agents can usually work around them via the existing tools.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End — same form as `start`. For all-day events this date is INCLUSIVE (end 2026-09-03 means the event runs through 3 September). | |
| start | Yes | Start — either an ISO 8601 timestamp WITH timezone (2026-07-28T10:00:00+02:00 or …Z), or a bare date (2026-07-28) for an all-day event. A timestamp without a zone is rejected. | |
| title | Yes | Event title (required) | |
| all_day | No | Force an all-day event; time components in start/end are then discarded. Not needed when start/end are already bare dates. | |
| location | No | ||
| time_zone | No | IANA zone, e.g. America/New_York. For timed events it preserves the NAMED zone so the event follows daylight saving (without it the event is stored as UTC and shows as GMT in Apple Calendar, and a recurring series will not shift with the clocks). For all-day events it decides which local day is covered. Always send it when you know the user's zone; defaults to UTC. | |
| calendar_id | No | Target calendar; only needed when several are writable | |
| description | No |
| Name | Required | Description |
|---|---|---|
| warning | No | |
| event_id | Yes | |
| calendar_id | Yes | |
| calendar_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already covering the write/non-destructive profile, the description adds substantial behavior: the availability check is LIVE, an overlap does NOT block creation but returns a `warning` the agent must relay to the user, only `blocks_time: true` events count as conflicts, and all-day Apple/iCloud entries are deliberately excluded. These are non-obvious traits an agent could not infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core write behavior and the overlap-warning rule, and every paragraph targets a distinct failure mode (double-booking, false conflicts, all-day dates, zone handling). The 'Baustelle Darmstadt' illustration and the DST explanation are slightly verbose, but they justify their length for a semantically tricky tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, yet the description still explains the salient `warning` field. Combined with the all-day, timezone, and calendar-selection rules, an agent has everything needed to call this correctly on the first attempt.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage the schema already carries much of the parameter detail, but the description adds real meaning: the all-day `end` date is INCLUSIVE ('2026-09-01' to '2026-09-03' creates a three-day event), both ends must use the same form, and time_zone governs DST persistence. Some of this duplicates the schema's own descriptions, so it is additive rather than decisive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Creates an event') plus the write-scope constraint ('in one of the calendars this access may write to'). An agent can immediately separate this from update_event, delete_event, and search_events without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance by naming siblings: call get_availability first when booking a specific day, and list_calendars to find writable calendars. It also states the when-not condition ('calendar_id is only needed when several calendars are writable'), so the agent knows when a parameter can be omitted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Identifier from create_event | |
| calendar_id | No |
| Name | Required | Description |
|---|---|---|
| deleted | Yes | |
| event_id | Yes | |
| calendar_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the destructiveHint=true annotation: provider-level deletion, sync propagation, irreversibility, organiser cancellation for participants, and the local-hide behavior of the wrong tool. The description carries the full behavioral burden and does it thoroughly, with no contradiction to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense paragraphs, but every sentence earns its place—scope, side effects, confirmation protocol, and alternatives. It front-loads the core action and uses an efficient cross-reference to update_event, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values don't need explaining. The description covers scope, permissions, irreversibility, participant impact, and alternative routing, making it complete enough for safe invocation of a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers event_id only ('Identifier from create_event'); calendar_id has no description. The description never mentions the parameters or their roles, so it doesn't compensate for the 50% schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Deletes an event'—a specific verb and resource—and immediately narrows scope to events this access created plus manageable ones. It also distinguishes itself from respond_to_event for invitations, so an agent can tell it apart from siblings without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when delete_event is appropriate ('events THIS access created' and manageable ones), when to confirm first (events not created by this access, events with other participants), and names respond_to_event as the right alternative for someone else's invitation. The cross-reference to update_event's four refusals adds further decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End of the range, ISO 8601 | |
| from | Yes | Start of the range, ISO 8601 (e.g. 2026-07-21T00:00:00Z) |
| Name | Required | Description |
|---|---|---|
| busy | Yes | |
| range | Yes | |
| sources | Yes | |
| warnings | Yes | |
| range_clamped | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, it discloses freshness limits ('reads are reused for up to 60 seconds, so an event created moments ago may briefly be missing'), the merge/no-copy read path, what is included and excluded (all-day and tentative in, cancelled out), the Apple/iCloud blocks_time quirk, and failure modes ('read: false in sources... additionally in warnings'). This is unusually rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core answer is front-loaded in the first sentence, and the following paragraphs are labeled by concern ('How the answer is produced', 'What busy contains', 'Completeness'), so scanning is easy. It is longer than a two-parameter read tool strictly needs, but nearly every sentence carries non-obvious semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still supplies the interpretation layer an agent needs (as_of, busy, blocks_time, read:false in sources, warnings) and explicitly tells the agent to surface those limitations to the user. Nothing needed to call or correctly relay results is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both required parameters (from, to) are fully documented in the schema at 100% coverage, so the baseline is 3. The description adds nothing about parameter syntax or formatting beyond what the schema already states; its detail is about output interpretation, not inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource with explicit scope: 'Returns the user's busy times in a given range, across all calendars shared with this access.' This is clearly distinct from search_events or list_calendars in substance, but no sibling tool is named to make the routing explicit, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete when-to-use branching tied to user intent: 'for "am I free / find me a slot", count only blocks_time: true' versus 'for "what do I have on", list everything'. It also sets an exclusion-style rule ('Never present a blocks_time: false entry as nonexistent'). It does not, however, contrast this tool against alternatives like search_events or list_calendars.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the calendars shared with this access, each with the detail level the user allowed.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| notice | No | |
| calendars | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool as read-only and non-destructive, so the description does not need to restate that. It adds substantial non-obvious behavior: calendars with readable:false are deliberately listed rather than omitted, writable:true defines where create_event may act, notice must be passed to the user rather than treated as a product failure, and sync_health describes Kalender Sync's own state, not availability. This goes far beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but each paragraph earns its place by explaining a distinct field or behavioral implication. It is front-loaded with the core purpose, then organized by field name. The notice and sync_health paragraphs are dense but prevent real agent missteps, so the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema and read-only annotations, the description is complete. It covers the meaning of readable, writable, notice, and sync_health, and it connects the results to get_availability and create_event. An agent has everything needed to call the tool and interpret its response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there are no parameter gaps to compensate for. The description appropriately spends its effort explaining the output fields and their meanings, which is the only semantic content an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Lists the calendars shared with this access, each with the detail level the user allowed.' It clearly distinguishes this read/list operation from the event-mutating siblings like create_event and delete_event by focusing on the calendar collection and per-calendar access metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance by linking list_calendars to related tools: readable:false calendars are missing from get_availability, and writable calendars are the ones create_event needs a calendar_id for. It does not explicitly say 'use this tool when you need to discover accessible calendars,' but the relationships and implications are strong enough that an agent can infer when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | For a recurring appointment: answer only this date ("occurrence") or every date ("series"). Required as soon as the appointment repeats. | |
| comment | No | Optional note for the organiser, sent with the answer | |
| event_id | Yes | The `event_id` from get_availability or search_events | |
| response | Yes | The answer to send to the organiser | |
| calendar_id | No | The `calendar_id` that came back beside the event. Always pass it — it is in the same result, and leaving it out costs a round trip whenever more than one calendar is available. |
| Name | Required | Description |
|---|---|---|
| needs | No | |
| scope | No | |
| title | No | |
| event_id | Yes | |
| question | No | |
| response | Yes | |
| warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's job is to name the specific side effect, which it does: the organiser is notified, and declining one occurrence versus a series sends different messages. This adds consequence context beyond the annotation and warns agents not to treat this as a silent calendar change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, and each subsequent paragraph covers one distinct decision: provenance, pass-back, scope, and refusal handling. There is no filler; the bolded scope instruction makes the main branch easy to scan and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, a destructive annotation, and a potentially ambiguous recurring-event case, every call-time decision is covered. The recurring scope edge case is resolved, the notification side effect is stated, and the refusal behavior is addressed; the output schema covers return-value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, raising the baseline, but the description goes well beyond the schema: it explains event_id provenance, requires calendar_id from the same result, and gives a precise decision rule for scope based on is_recurring and whether the user named a date. This directly improves invocation correctness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific action and resource: accepts, declines, or tentatively accepts an invitation someone else sent the user. The 'someone else sent' qualifier distinguishes it from create_event/update_event/delete_event, and the rest of the description ties it to a clear invitation-response workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete when-to-use context: use data from get_availability or search_events, pass event_id and calendar_id straight back, and ask about scope only when the user named no date. It does not explicitly enumerate sibling alternatives as the wrong choice, though the warning about removing an invitation without answering implies why delete_event alone is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the range, ISO 8601. Default: 85 days ahead. | |
| from | No | Start of the range, ISO 8601. Default: 7 days ago. | |
| query | Yes | Text to look for (case-insensitive substring) |
| Name | Required | Description |
|---|---|---|
| range | Yes | |
| matches | Yes | |
| sources | Yes | |
| warnings | Yes | |
| truncated | Yes | |
| range_clamped | Yes | |
| unsearchable_calendars | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only the safety profile (readOnly, non-destructive, closed-world). The description goes far beyond: visibility-rendered scope, the warning emitted for free/busy-only calendars, which fields are returned for manageable calendars, the 92-day span and one-year lookback caps, default range, exclusion of cancelled events, and the instruction not to filter blocks_time:false/all-day events.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence, and every subsequent sentence carries non-redundant behavior (visibility, warnings, returned fields, range caps, blocks_time caveat). It is on the long side, but little of it is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with an output schema, annotations, and a small parameter set, the description covers everything needed to invoke it correctly and interpret results: scope, limits, defaults, warnings, and the caveat about false negatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the range behaves like get_availability with a single span capped at 92 days and a one-year lookback bound, and it confirms the from/to defaults. It does not add anything for the required query parameter beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('finds events by text') plus the exact matching semantics (case-insensitive substring over title, location, description). It also scopes itself against the sibling get_availability, so an agent can distinguish it without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: use this to find events by text, then act on the returned event_id/calendar_id directly 'instead of calling get_availability again.' It also states the key false-negative condition ('No match is thus NOT proof that no such event exists') and the free/busy visibility limitation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends feedback from the user to the Kalender Sync team — for example when the user wanted to do something these tools cannot do yet (editing an existing event, answering an invite, …), or when something looks broken.
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.
Replies: for a bug report the team may send the user a single reply about it by default — set contact_ok to false if the user does not want that. For the other categories it is the reverse: no reply is sent unless the user asked for one, in which case set contact_ok to true. Never a newsletter signup either way.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The user's feedback in their own words (what they wanted, what happened). | |
| category | Yes | missing_capability: the user wanted something the tools cannot do. bug: something misbehaved. other: everything else. | |
| contact_ok | No | May the team send one reply about this feedback? Omit to use the default: yes for `bug`, no for the other categories. Set false if the user declined a reply, true if the user asked for one. |
| Name | Required | Description |
|---|---|---|
| received | Yes | |
| feedback_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the annotations, such as the default reply behavior per category, the distinction between bug and other categories for contact_ok, and the rule about not including unsolicited calendar content. Since annotations only provide basic booleans (readOnlyHint: false, destructiveHint: false), the description adds substantial value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first paragraph explaining purpose, a second paragraph with when-to-use rules, and a third paragraph explaining contact_ok behavior. Every sentence provides necessary guidance without redundancy. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, 1 enum, 100% schema coverage, and an output schema), the description adequately covers usage rules and behavioral details. The only minor gap is the lack of explicit mention of what the tool returns (output schema exists but no description of response). However, since an output schema is present, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 100%, the description adds context beyond the schema by explaining the contact_ok default behavior based on category (bug vs others) and the nuance of when to set it to true or false. The description could slightly improve by explicitly linking category values to the feedback scenarios mentioned in the first paragraph, but overall adds meaningful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool sends feedback from the user to the Kalender Sync team, and provides concrete examples of when it should be used (e.g., missing capabilities, broken features). This distinguishes it well from sibling tools like create_event or update_event which handle calendar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call the tool ('only when the user explicitly asked to send feedback'), when not to call it ('never send feedback on your own initiative'), and provides clear rules about including calendar content. It also gives nuanced guidance on the contact_ok parameter based on feedback category.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
Events THIS access created (via event_id from create_event) — always.
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
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | New end — same form as `start`; INCLUSIVE for all-day events. | |
| start | Yes | New start — ISO 8601 with timezone (…+02:00 or …Z), or a bare date (2026-07-28) for an all-day event. | |
| title | Yes | ||
| all_day | No | Force an all-day event; time components in start/end are discarded. | |
| event_id | Yes | Identifier from create_event | |
| location | No | ||
| time_zone | No | IANA zone, e.g. America/New_York. Preserves the named zone for timed events (so recurrences follow daylight saving) and decides the local day for all-day ones. Defaults to UTC. | |
| calendar_id | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| updated | Yes | |
| event_id | Yes | |
| calendar_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the destructive/mutating profile, and the description adds substantive behavioral context beyond them: the all-day↔timed conversion, complete-new-state semantics, and all four refusal modes with remediation. These are meaningful details the structured fields could not convey, and they are consistent with readOnlyHint=false and destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence earns its place — the numbered event-addressability list and bulleted refusal cases are scannable and front-loaded. Minor trims are possible in the parenthetical clarifications, but there is no padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, 4-refusal-case tool with two addressability modes, nearly everything an agent needs is present, and the output schema covers the response contract. The only gap is the fate of unspecified optional fields (description, location) given that only title/start/end are declared 'complete new state'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 56%, and the description compensates well by explaining that title/start/end constitute the complete new state and how passing timestamps vs. bare dates flips an event between all-day and timed. It leaves format details (ISO 8601, IANA zones) to the schema as appropriate, but does not clarify what happens to optional fields like location or description when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Updates an event') and immediately defines what that means — title/start/end describe the complete new state, including the all-day nuance. It also references sibling tools (create_event, respond_to_event, list_calendars) so an agent can distinguish this from create/delete/respond flows without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
This is exemplary. The description explicitly states the two kinds of events that are addressable and enumerates all four refused cases, each with 'what to do instead' — routing to respond_to_event with response: 'declined' for organizer conflicts and to the source calendar for synced copies. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_availability2 fields changedOutput schema / properties / busy / items / properties / blocks_timeAdded value: +{
+ "type": "boolean"
+}Output schema / properties / busy / items / requiredPrevious value: -[
- "start",
- "end",
- "is_all_day",
- "calendar_id",
- "calendar_name"
-]New value: +[
+ "start",
+ "end",
+ "is_all_day",
+ "blocks_time",
+ "calendar_id",
+ "calendar_name"
+]search_events2 fields changedOutput schema / properties / matches / items / properties / blocks_timeAdded value: +{
+ "type": "boolean"
+}Output schema / properties / matches / items / requiredPrevious value: -[
- "start",
- "end",
- "is_all_day",
- "calendar_id",
- "calendar_name"
-]New value: +[
+ "start",
+ "end",
+ "is_all_day",
+ "blocks_time",
+ "calendar_id",
+ "calendar_name"
+]get_availability6 fields changedOutput schema / properties / busy / items / properties / attendeesAdded value: +{
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "email": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "optional": {
+ "type": "boolean"
+ },
+ "organizer": {
+ "type": "boolean"
+ },
+ "self": {
+ "type": "boolean"
+ },
+ "status": {
+ "enum": [
+ "accepted",
+ "declined",
+ "tentative",
+ "needs_action"
+ ],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / busy / items / properties / event_idAdded value: +{
+ "type": "string"
+}Output schema / properties / busy / items / properties / has_other_attendeesAdded value: +{
+ "type": "boolean"
+}Output schema / properties / busy / items / properties / is_organizerAdded value: +{
+ "type": "boolean"
+}Output schema / properties / busy / items / properties / is_recurringAdded value: +{
+ "type": "boolean"
+}Output schema / properties / busy / items / properties / more_attendeesAdded value: +{
+ "type": "number"
+}list_calendars2 fields changedOutput schema / properties / calendars / items / properties / manageableAdded value: +{
+ "type": "boolean"
+}Output schema / properties / calendars / items / requiredPrevious value: -[
- "id",
- "name",
- "provider",
- "visibility",
- "readable",
- "writable",
- "sync_health"
-]New value: +[
+ "id",
+ "name",
+ "provider",
+ "visibility",
+ "readable",
+ "writable",
+ "manageable",
+ "sync_health"
+]respond_to_eventsearch_events6 fields changedOutput schema / properties / matches / items / properties / attendeesAdded value: +{
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "email": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "optional": {
+ "type": "boolean"
+ },
+ "organizer": {
+ "type": "boolean"
+ },
+ "self": {
+ "type": "boolean"
+ },
+ "status": {
+ "enum": [
+ "accepted",
+ "declined",
+ "tentative",
+ "needs_action"
+ ],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / matches / items / properties / event_idAdded value: +{
+ "type": "string"
+}Output schema / properties / matches / items / properties / has_other_attendeesAdded value: +{
+ "type": "boolean"
+}Output schema / properties / matches / items / properties / is_organizerAdded value: +{
+ "type": "boolean"
+}Output schema / properties / matches / items / properties / is_recurringAdded value: +{
+ "type": "boolean"
+}Output schema / properties / matches / items / properties / more_attendeesAdded value: +{
+ "type": "number"
+}create_event1 field changedInput schema / properties / time_zone / descriptionPrevious value: -"IANA zone (e.g. Europe/Brussels) deciding which local day an all-day event covers. Defaults to UTC. Ignored for timed events, which carry their own offset."New value: +"IANA zone, e.g. America/New_York. For timed events it preserves the NAMED zone so the event follows daylight saving (without it the event is stored as UTC and shows as GMT in Apple Calendar, and a recurring series will not shift with the clocks). For all-day events it decides which local day is covered. Always send it when you know the user's zone; defaults to UTC."update_event1 field changedInput schema / properties / time_zone / descriptionPrevious value: -"IANA zone deciding which local day an all-day event covers. Defaults to UTC."New value: +"IANA zone, e.g. America/New_York. Preserves the named zone for timed events (so recurrences follow daylight saving) and decides the local day for all-day ones. Defaults to UTC."create_event4 fields changedInput schema / properties / all_dayAdded value: +{
+ "description": "Force an all-day event; time components in start/end are then discarded. Not needed when start/end are already bare dates.",
+ "type": "boolean"
+}Input schema / properties / end / descriptionPrevious value: -"End, ISO 8601 with timezone"New value: +"End — same form as `start`. For all-day events this date is INCLUSIVE (end 2026-09-03 means the event runs through 3 September)."Input schema / properties / start / descriptionPrevious value: -"Start, ISO 8601 WITH timezone — e.g. 2026-07-28T10:00:00+02:00 or …Z. Rejected without a zone."New value: +"Start — either an ISO 8601 timestamp WITH timezone (2026-07-28T10:00:00+02:00 or …Z), or a bare date (2026-07-28) for an all-day event. A timestamp without a zone is rejected."Input schema / properties / time_zoneAdded value: +{
+ "description": "IANA zone (e.g. Europe/Brussels) deciding which local day an all-day event covers. Defaults to UTC. Ignored for timed events, which carry their own offset.",
+ "type": "string"
+}update_event4 fields changedInput schema / properties / all_dayAdded value: +{
+ "description": "Force an all-day event; time components in start/end are discarded.",
+ "type": "boolean"
+}Input schema / properties / end / descriptionPrevious value: -"New end, ISO 8601 with timezone"New value: +"New end — same form as `start`; INCLUSIVE for all-day events."Input schema / properties / start / descriptionPrevious value: -"New start, ISO 8601 with timezone (e.g. …+02:00 or …Z)"New value: +"New start — ISO 8601 with timezone (…+02:00 or …Z), or a bare date (2026-07-28) for an all-day event."Input schema / properties / time_zoneAdded value: +{
+ "description": "IANA zone deciding which local day an all-day event covers. Defaults to UTC.",
+ "type": "string"
+}get_availability1 field changedOutput schema / properties / sources / items / properties / retryableAdded value: +{
+ "type": "boolean"
+}search_events1 field changedOutput schema / properties / sources / items / properties / retryableAdded value: +{
+ "type": "boolean"
+}send_feedback1 field changedInput schema / properties / contact_ok / descriptionPrevious value: -"true ONLY if the user explicitly agreed to one reply about this feedback."New value: +"May the team send one reply about this feedback? Omit to use the default: yes for `bug`, no for the other categories. Set false if the user declined a reply, true if the user asked for one."list_calendars1 field changedOutput schema / properties / noticeAdded value: +{
+ "type": "string"
+}list_calendars2 fields changedOutput schema / properties / calendars / items / properties / writableAdded value: +{
+ "type": "boolean"
+}Output schema / properties / calendars / items / requiredPrevious value: -[
- "id",
- "name",
- "provider",
- "visibility",
- "readable",
- "sync_health"
-]New value: +[
+ "id",
+ "name",
+ "provider",
+ "visibility",
+ "readable",
+ "writable",
+ "sync_health"
+]create_eventdelete_eventget_availabilitylist_calendarssearch_eventssend_feedbackupdate_eventCalendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Scheduling infrastructure for AI agents across Google and Microsoft calendars.
Governed memory and workspace for any AI: tasks, calendar, mail and pages, with per-action consent.
Add one secure layer between your agents and this server.
