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

Beyond the readOnlyHint annotation, it discloses output semantics (images here are supplemental; boat_details is canonical), a workflow constraint (use only booking_detail_mod's server-calculated totals after changes), and a pricing caveat (quote customer_cost_summary.full_customer_cost; deposits are returned separately and excluded). This is substantive context the annotations cannot carry.

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?

Purpose is front-loaded and every sentence carries routing, constraint, or output information. It is somewhat dense with branching instructions (media, extras, totals, final offers) that could be tightened, but nothing is pure filler.

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 and a read-only annotation, the description compensates by naming the response fields an agent needs (customer_cost_summary.full_customer_cost, separate deposits) and by specifying the follow-up tools for mutation and booking. An agent has enough to call and interpret this tool correctly.

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%, so all five parameters are already documented in the schema, including the DD/MM/YYYY formats. The description adds only the sourcing constraint for id_boat/id_tbf1 ('exactly as returned by search_boats'), which the schema phrasing partly mirrors, so the baseline of 3 holds.

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 a specific verb and resource ('Return date-specific availability, pricing, extras and booking choices') and immediately distinguishes itself from the sibling boat_details for media. An agent can tell what this tool is for and what it is not for 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?

Explicit routing: call boat_details instead when only photos/media are wanted, and call booking_detail_mod after the customer changes extras, passengers, currency, ports or payment options. It also states the prerequisite that id_boat and id_tbf1 must come verbatim from search_boats.

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