create_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 does well: it discloses that invitations go to every attendee, that answers surface in list_calendar_events under attendees[].status, that normal send rules apply, and that it must be called once. It omits permission/auth requirements and what happens to the email on failure.

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?

Dense but front-loaded: the core action and the critical 'call once' warning are emphasized, and each subsequent sentence covers a distinct parameter group. No filler, though the run-on parameter block could be trimmed.

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 13-parameter, no-annotation, no-output-schema tool, the description addresses time handling and the invitation lifecycle but leaves several parameters and the return behavior undescribed. It is adequate but has clear gaps an agent would have to guess at.

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 0% across 13 parameters, so the description must compensate. It explains start formats, timezone, end/duration_minutes (default 30), all_day exclusivity, message, and in_reply_to well, but leaves the required 'address' parameter, plus location, description, and optional_attendees, entirely unexplained.

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 a specific verb and resource ('Schedule a meeting from this inbox and email the invitations') and clarifies the actor role ('you are the organizer'). It is clearly distinguishable from send_email and update_calendar_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?

Gives a strong usage constraint — 'Call it ONCE per meeting: it emails every attendee' — which prevents duplicate invitations. However, it never explicitly contrasts with siblings like update_calendar_event or cancel_calendar_event for modifying/removing an existing meeting.

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