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

Annotations declare non-readonly, idempotent and non-destructive, and the description stays consistent while adding genuinely new behavioral facts: what gets frozen, that nothing is booked, that checkout_id and a beep.rent link are returned, and the replay rule for options. That is context beyond the annotation set rather than a restatement of it.

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-loaded with the trigger condition, then effects, then the caveat and the pre-call obligation, then a compact example. Content is dense but every sentence carries a distinct rule; the opening sentence is long and could be split for readability.

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?

An output schema exists, so return values need not be detailed, and the description still names checkout_id and continue_url usefully. For a checkout-freezing tool the notable remaining gap is how long the frozen price/checkout_id stays valid and whether it must be re-created if it expires.

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 0% for a large nested options object, but the description compensates with the single most important rule: 'Resend every option you applied in get_offer.' The inline example also conveys parameter provenance (search_id from search, offer_ref from offer). The market parameter and the checkout's price-lock lifetime remain unexplained, so not a 5.

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 plus its exact semantic effect: it freezes price, deposit, options and policies and returns checkout_id and a continue_url. Crucially it distinguishes itself from the reservation-writing siblings by saying 'Does not book anything', so an agent can tell it apart from create_reservation or confirm_reservation_code.

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 triggering condition ('Use after get_offer when the user chose an offer') and a prerequisite ('Show the user the price, the deposit and the cancellation policy before calling'), plus the important exclusion that it does not book. It stops short of naming the follow-up sibling (create_reservation) explicitly, which keeps it from a 5.

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