Create Event Invitee (Scheduling API)

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description meaningfully adds the confirm=true gate and the scheduled_events:write scope requirement, both operational facts the agent must satisfy before invoking. It does not explain side effects on the referenced event or response behavior, keeping it short of 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?

Two sentences, no filler, and the mutation/confirm constraint is front-loaded. It is appropriately terse, though the title restatement in sentence one is near-redundant with the name.

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?

This is a high-complexity tool: 11 parameters, deeply nested polymorphic objects, mutually exclusive payload/payload_file/body-flag paths, and no output schema. A two-sentence description covering only confirm and scope leaves the agent without guidance on which input mode to use or how the required-but-empty top-level schema fits together.

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 82%, well above the 80% threshold, so the schema already documents the nested invitee, location, tracking, and payload fields. The description adds no parameter-level guidance (it never mentions payload vs. top-level fields, payload_file exclusivity, or account selection), so the baseline 3 applies.

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 first sentence is essentially the title restated ('Create Event Invitee (Scheduling API)'), which alone would be tautological. The second sentence adds that this mutates Calendly state, which clarifies the nature of the operation, but nothing distinguishes it from nearby writers like create_no_show or create_contact.

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 a hard precondition (confirm=true) and the required scope (scheduled_events:write), which is actionable guidance for calling it. However, it offers no when-to-use vs. alternatives routing among the many sibling write tools, so usage is only partially implied.

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