Update calendar event

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers extensively: partial-update semantics, empty-string clearing, duration preservation when only start_time changes, per-occurrence vs whole-series editing, RRULE replacement/clearing, series-move effects on exceptions with removed_exceptions, unsupported and_following, and no invitations. This is exemplary behavioral disclosure.

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?

Densely packed and logically ordered, starting with the basic semantics and then handling recurrence edge cases, limitations, and reminders. Every sentence adds behavioral nuance needed for correct invocation, with no filler 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?

Coverage is strong for the hard parts: recurrence scoping, series moves, exception counting, and the unsupported and_following case, and it points to warnings in the result. Minor gaps exist around end_time semantics, datetime format, and not-found behavior, but these are small given the complexity and the presence of an output schema.

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 description coverage is 0%, so the description must compensate. It explains the nuanced semantics of start_time (moves event, keeps duration), occurrence (recurrence_id scope), recurrence (RRULE vs empty string), and clearing description/location. Only end_time and event_title lack explicit mention, but their meanings are obvious from names.

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 'Change an existing event' with a specific verb and resource. The contrast with siblings (create/delete/get/list) is clear from 'existing' and the subsequent modification semantics, so an agent can distinguish it 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 names delete_event(..., and_following=true) as the alternative for unsupported 'this and all following' changes and points to list_events for retrieving recurrence_id. It does not explicitly cover when to use create_event vs update_event, but the 'existing event' qualifier makes that implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.