Create booking

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

Annotations only declare the safety profile (non-read-only, open-world, non-idempotent, non-destructive); the description adds the behavior that actually matters: the record lands as a draft, not a confirmed booking, and no notification is sent until it is booked. It also discloses the required UI handoff via form_url, which is not visible anywhere in the schema.

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 the core action, then the draft/notification consequence, then the form_url step — every sentence carries information. The parenthetical reference "Copies the booking as Duplicate in its sidebar does" is slightly awkward and could be tightened, but nothing is wasted.

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?

With no output schema, the description still tells the agent what comes back (a draft found via list_drafts plus a form_url to complete the booking) and what state change occurred (nothing notified). For a one-parameter, open-world mutation tool this covers everything needed to invoke and follow up correctly.

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% and the single property is already documented as "Booking to copy, from list_bookings," so the baseline is 3. The description earns an extra point by enumerating exactly what is inherited from that id (customer, address, service, extras, price), telling the agent what the copy will contain.

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+resource ("Start a new booking") and immediately scopes the mechanism: a copy of an existing booking carrying the same customer, service and price. It draws a direct analogy to the Duplicate sidebar action, which lets an agent distinguish it from siblings like reschedule_booking or cancel_booking 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?

Clearly states the trigger condition (you want a new booking that reuses an existing one's customer/service/price) and names the required follow-through: open form_url to pick a date. It points to list_drafts and list_bookings as the relevant companions. It stops short of stating when NOT to use it (e.g., an existing booking should be rescheduled rather than copied), so 4 rather than 5.

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