create_event

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive local write. The description adds genuinely new operational behavior: the UNKNOWN_WRITE_OUTCOME case (read the calendar before retrying a create) and the INVALID_INPUT case (inspect schema and fix rather than blind retry). It does not cover permission/auth requirements, which keeps it from a 5.

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 purpose and the 'load the input schema first' instruction, then proceeds in priority order (timed rules, all-day rules, optional/unsupported fields, error handling). It is dense and duplicates some schema text, but nearly every sentence carries a distinct constraint an agent must 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?

There is no output schema, yet the description never states what creation returns (e.g., the new event ID and its format), only hinting at 'returned IDs' when discussing examples. Error paths and input semantics are thorough, but the return-value gap leaves this incomplete for a mutating create 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 coverage is 100%, so the baseline is 3, but the description contributes cross-parameter rules beyond field-level docs: title/start/end must be nested inside fields, offsets must match the IANA zone on the requested date, Z timestamps force timezone=UTC, and end must be strictly later than start. All-day exclusivity and no-timezone rules add coherence guidance for the schema's two-argument shape.

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 a specific verb and resource plus a scope qualifier: 'Create one non-recurring event.' The 'non-recurring' constraint immediately separates it from update_event and implies recurrence is out of scope, so an agent can select it 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 clear context for use (new single event, calendar_id from list_calendars, load schema first) and names the unsupported surface (attendees, reminders, extra keys). It does not explicitly say 'to modify an existing event use update_event,' but the create-only framing and prerequisite for calendar_id make the selection unambiguous.

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