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

Annotations already declare non-read-only, non-idempotent, open-world behavior, but the description adds materially: a customer record is created as a side effect, a confirmation email may be sent, connected calendars may be updated, and times are converted to UTC. These external side effects are exactly what an agent needs before committing to a booking.

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?

Three sentences, front-loaded with the WRITE classification, the effect statement, and the guardrail, ending with the endpoint. No filler, and the riskiest information (outbound email, calendar writes) is surfaced before the alternative routing.

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 an 11-parameter mutating tool with no output schema, the description covers prerequisites, side effects, and time semantics well. The remaining gap is the return value: with no output schema, the agent has no idea whether an appointment id comes back for later update/cancel calls.

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%, so the baseline is 3, but the description adds meaning beyond the schema: ids must be sourced from bookafy_list_staff and bookafy_list_services, the customer is derived from the provided name/email/phone, and start/end are normalized to UTC. Only the optional price/title/description/custom_fields semantics are left entirely to the schema.

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 an explicit verb, 'WRITE: book an appointment', then names the resource and the three entities involved (customer, staff member, service). It distinguishes itself from sibling list/update/cancel tools by naming where the ids come from (bookafy_list_staff, bookafy_list_services), so the agent can identify the tool 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 a clear exclusionary rule: 'only call it when the user clearly asked to book', which is a real when-not condition for a tool with external side effects. It also points to sibling tools for prerequisite ids. It does not explicitly contrast with bookafy_update_appointment for modifying an existing booking, so it stops short of a full when/when-not/alternatives treatment.

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