update_event

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial behavioral detail beyond them: omitted/null properties are preserved while empty strings for description/location clear them, all-day end is exclusive, timezone is forbidden for all-day events, and offsets must match the retained/supplied zone. It also documents that CONFLICT must trigger a re-read rather than a blind retry, which is exactly the safety context an agent needs. No contradiction with the 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?

It is long but front-loaded: the goal and required identifier set come first, then editing semantics, then error handling. Nearly every sentence encodes a distinct constraint, though the revision-copying rule repeats what the schema already says and the opening 'Load the full input schema first' is somewhat meta.

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 destructive, non-idempotent mutation with no output schema, the description covers the prerequisite read, optimistic-concurrency handling, field-clearing semantics, timezone edge cases, recurring-series restrictions, and recovery from all three named error outcomes. An agent has everything needed to call it without guessing.

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 cross-parameter relationships the schema fields state only individually: the offset/timezone consistency rule, the requirement that only changed fields go inside patch, and the whole_series gate for recurring resources. The verbatim-including-quotes instruction for expected_revision is reinforced rather than newly added, keeping it short of a 5.

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 gives a specific verb (Edit) and scopes it to one resource identified by {calendar_id, event_id, expected_revision, patch}, which maps unambiguously to update_event. It also names get_event as the prerequisite step, distinguishing it from the read sibling. 'One resource' is slightly abstract versus saying 'event', but the parameters remove any ambiguity.

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 states the required workflow (call get_event first, copy the revision verbatim), explicitly lists unsupported operations (invitations, occurrence edits, recurring timing changes with exceptions), and routes recurring edits to whole_series=true. Error paths (CONFLICT, INVALID_INPUT, UNKNOWN_WRITE_OUTCOME) each get a prescribed next action, so when-to-use and when-not-to-use are both covered.

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