List bookings

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds non-obvious behaviour: free-text answers and single-use reschedule links are withheld unless include_contact_details is set. That data-exposure disclosure goes meaningfully beyond the annotations, though pagination/result-shape behaviour is only covered by the schema's 'start' parameter.

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 dense but front-loaded sentences: return shape first, then filter dimensions, then the permission caveat. No filler, though the filter enumeration is a long run-on that could be tightened.

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 19-parameter, no-required-argument list tool with no output schema, the description covers return fields, filter scope, and the sensitive-data gate. Remaining gaps (pagination via 'start', sort defaults) are documented in the schema itself.

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 79%, but the description still adds real semantics: after/before are compared against the booking's start/end including buffers, and 'Participants carry customer_id only'. These clarify filter meaning beyond the ISO-8601 phrasing in 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?

The description enumerates exactly what a booking record contains (status, service, resource, times, price, spaces, participants) and what can be filtered, so an agent knows this is the paginated booking-retrieval endpoint. It distinguishes itself from find_available_* siblings implicitly by being the only one returning bookings, but never names an alternative list tool.

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?

Usage is implied rather than stated: it tells the agent which filters exist and routes one sub-need ('use get_customer for names'), but gives no when-to-use vs when-not guidance or exclusions relative to siblings like find_available_intervals or list_services.

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