Update an event

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

Annotations already establish mutability and idempotency, and the description adds meaningful operational behavior beyond them: omitted fields are preserved, updating only start_time alters duration, and send_notifications controls attendee emails with a default of true. It does not contradict the annotations, though it does not discuss how to explicitly clear a field.

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 key behavioral rule and sibling distinction are front-loaded in two tight sentences, followed by a compact Args block that maps directly to the schema. There is no filler or redundancy.

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 nine parameters and zero schema descriptions, the description is remarkably complete: all args are covered, defaults are stated, the move_event alternative is handled, and the attendee-notification side effect is disclosed. The only minor gap is that clearing a field is not explicitly addressed, and calendar_id's primary default is left to the 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 carries the full burden and succeeds. Every one of the nine parameters is explained with field purpose, provenance, format, or default, and it even flags event_id as semantically required despite the schema's default string.

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 starts with a specific verb and resource: 'Change fields on an existing event' and immediately adds the crucial distinguishing semantic 'Omitted fields are left untouched.' This clearly separates it from create_event, delete_event, and especially move_event.

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 tells the agent when not to use this tool: to reschedule while keeping duration, use move_event instead, and explains why changing only start_time here leaves the old end time in place. It also instructs where to source event_id and account, giving clear invocation context.

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