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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that a prepared booking has no fixed expiry, that the underlying search session behind quoteId is what expires, the exact surfaced error ('This booking is unavailable'), and the recovery path (re-run hotel_search and re-quote). It also discloses failure modes (400 when searchKey is omitted) and an internal mechanism (searchKey warms the cancellation-policy cache), none of which appears in structured fields.

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?

It is front-loaded with the outcome and return values before prerequisites, and nearly every clause carries operational information. It loses a point for redundancy: the searchKey requirement is stated twice ('omitting it is a 400' and 'the searchKey is required'), and it is packed into one long block rather than split by concern (inputs / auth / next step).

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 6-parameter tool with nested objects and no output schema, the description covers the return payload, the ID alias, every required input's origin, the session requirement, the error surface, and the exact next tool to call. Nothing an agent needs to invoke this correctly is missing, especially since there is no output schema to fall back on.

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 only 50% and three nested/optional params (specialRequests, contactPerson.countryCode, guest email/phone/isLeadGuest) are undocumented, but the description compensates by defining roomIndex as 0-based, requiring 'one guest entry per adult', and pinning quoteId and searchKey to their source tools. The nested rooms/guests/contactPerson shapes, which the flat coverage number understates, are all spelled out in prose.

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 ('Prepares a booking for a chosen room offer') and also names what it returns ('final price plus a preparedBookingId'). It explicitly routes to distinct siblings ('send preparedBookingId to create_checkout ... or get_payment_url ...; B2B partners use confirm_booking'), so an agent can separate this pre-commit step from the commit step 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 explicit preconditions and provenance for each input: quoteId 'from get_hotel_rooms', searchKey 'the SAME one from hotel_search', and 'Collect every guest's first/last name and a contact email + phone from the user before calling'. It names when a different tool must run first ('for a guest booking, first call guest_login ... pass the returned token as sessionToken') and enumerates three downstream alternatives with a recommendation, which is the full when/alternatives picture.

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