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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description isn't burdened with safety disclosure. It still adds real value by stating a privacy behavior the annotations cannot convey: customer cancel/reschedule link ids are never returned, and it pins the underlying endpoint (GET /bookings).

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 short sentences, front-loaded with purpose and output fields, followed by filtering guidance and one behavioral caveat. No filler or restated title.

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 properly carries the return-shape burden by naming the fields and the excluded link ids; pagination is adequately covered by the offset/next_offset schema text. Minor gaps remain on default ordering and whether cancelled bookings appear in this list.

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% and every parameter is documented in-schema, so the baseline is 3. The description restates the filter/search/single-id behaviors without adding syntax, defaults, or interaction rules (e.g., whether search_term is ignored when booking_id is set).

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+resource ("List bookings") and enumerates the returned fields (time, product, duration, quantity, price, customer contact details), so the agent knows exactly what this returns. It does not, however, distinguish itself from close siblings like appointo_list_cancelled_bookings or appointo_list_appointments.

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?

"Filter upcoming/past or search; pass booking_id for one booking" gives clear in-tool usage modes, but those modes are already implied by the schema's status/search_term/booking_id params. There is no guidance on when to pick this over list_appointments, list_cancelled_bookings, or list_subscription_contracts.

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