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

Discloses far more than the annotations: enumerated failure modes (422 missing_fields for required customer fields, 400 invalid_param for past times, 409 slot_unavailable for taken slots), immediate confirmation, Google Calendar and GoHighLevel sync side effects, and the appointment.booked event. It also clarifies that no message is sent to the customer, which an agent could otherwise assume given conversation_id. This is consistent with destructiveHint=true and idempotentHint=false.

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-loads the purpose, then proceeds through failure modes, side effects, the availability caveat, and parameter notes in a logical order. Dense but nearly every clause carries information; only the parenthetical error codes add slight clutter.

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 destructive, non-idempotent write with 12 parameters, nested customer/location objects and no output schema, the description covers inputs, error paths and downstream side effects well. It does not describe the returned appointment object or how optional fields like cost, notes and vehicle_info are used, though those are largely pass-through.

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?

With 58% schema coverage and 12 parameters, the description compensates for the trickiest ones: date/time are the customer's wall-clock values interpreted in timezone (account timezone when omitted), conversation_id links the booking without notifying the person, and required customer fields are enforced server-side. It adds no meaning for cost, notes, location, vehicle_info or duration_minutes beyond what the schema says, so it falls short of full coverage.

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', 'Books a slot the way the portal calendar does') and implicitly separates it from get_availability, reschedule_appointment and update_appointment by framing this as the create path that requires availability to be checked first. An agent can pick this out from the siblings without opening the 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 explicit routing guidance: 'Business hours are not checked here: call availability first to offer open times', which names the prerequisite sibling get_availability. It also explains when to pass conversation_id. It does not explicitly contrast with reschedule_appointment or update_appointment for existing bookings, which keeps it short of a 5.

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