Create appointment

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

Annotations already declare destructive=true, openWorld=true and idempotent=false, so the safety profile is covered; the description adds real context beyond that: services are booked sequentially from start_at at catalogue price, and the booking can send a real confirmation to the client. The only thing left vague is what the call returns on success or how the over-booking warning surfaces in this tool's own response.

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 compact sentences, front-loaded with what the tool does before the prerequisites and side effects. Every clause earns its place – the calendar analogue, the sequential booking, the client notification and the double-booking warning all change agent behavior.

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 4-parameter destructive mutation with no output schema, the description covers ordering, pricing, external side effects and the slot-checking prerequisite. The remaining gap is the response shape, which is neither documented here nor in an output schema.

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 100%, so every parameter is already documented, including the walk-in default and the team-member default. The description reinforces semantics (services run one after another from start_at with a single team member) but adds no format, ordering or constraint detail the schema does not already carry. Baseline 3 is appropriate.

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 ('Book an appointment') plus the key inputs (services, team member, start time), and anchors it to a concrete analogue: 'as New appointment in the calendar does'. An agent can distinguish it from list_appointments, reschedule_appointment and find_available_slots 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 an explicit prerequisite ('Find free times with find_available_slots first') and a concrete consequence of skipping it ('Fresha books over other appointments and returns its warnings'). It also routes to get_client for the notification-settings question, so both when-to-use and which sibling to consult are spelled out.

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