Create calendar event

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

With no annotations present, the description carries the full burden and delivers substantial behavioral detail: the return value (iCalendar UID), timezone interpretation for ISO 8601 values, the non-obvious end_date-inclusive semantics for all-day events, the constraint that the first occurrence must match the RRULE, and DST behavior. It stops short of disclosing error/failure behavior and idempotency, 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?

A single ~130-word paragraph ordered from the core action to return value, time semantics, all-day handling, and recurrence rules. Every sentence carries high-value information, the RRULE examples are concrete, and the subtle end_date-inclusive and DST notes earn their place. 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?

For a tool with 7 parameters, 0% schema coverage, and no annotations, the description covers the hardest parts—timezone, all-day, recurrence, and return value (with an output schema also present). The remaining gaps are calendar_name resolution (must the agent derive it from list_calendars?) and expected error behavior on invalid input. These are material for a create operation but secondary to the semantics already disclosed.

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 richly documents the genuinely ambiguous parameters: start_time/end_time (ISO 8601, timezone handling, date-only convention) and recurrence (exact RRULE format with three concrete examples plus constraint). Self-evident fields like location and description need no elaboration. However, calendar_name—a required parameter—is never explained as display name vs. ID or connected to list_calendars.

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+resource: 'Publish a new event to an iCloud calendar.' The creation intent is unmistakable and clearly distinguishes this tool from siblings like get_event, update_event, delete_event, and list_events. An agent can differentiate it 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?

While it never explicitly names alternatives or says 'use this instead of update_event,' it gives clear operational context: date-only values signal all-day events, and recurrence requires an RRULE whose first occurrence must match the rule. The conditional guidance ('To make it repeat...', 'Give date-only values...') effectively tells the agent how to shape the call for each scenario. It lacks explicit exclusions, so not a 5.

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