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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false. The description adds behavioral context beyond annotations: quote_id expires (expires_at), meal_plan is included only when supplier provides it, rate_plan_requested/rate_plan_matched echo the filter, and a booking_url is returned. No contradiction; the description enriches the safety profile with time-sensitivity and conditional output behavior.

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?

The description is moderately long but every sentence adds value: purpose, return highlights, time-sensitivity, sequencing, and authoritative-price warning. It is front-loaded with the core function and then provides critical usage notes. No filler or repetition of schema details.

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?

Given 8 parameters, no output schema, and moderate complexity, the description covers essential return fields (best room, all-in total, cancellation policy, booking_url, quote_id, expires_at), conditional behaviors, and sequencing guidance. It also clarifies the authoritative nature of the price, ensuring the agent has all needed context to call correctly and interpret results.

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 the schema already documents all 8 parameters with types and constraints. The description adds a little context (e.g., meal_plan behavior relates to rate_plan, residency should be asked traveler), but most parameter meaning is already in the schema. Baseline of 3 applies when schema covers parameters thoroughly.

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: 'Check real-time availability and get a firm price quote for a property, dates, and occupancy.' Clearly distinguishes from siblings by naming search_stays and get_stay_details as non-authoritative for pricing, and explicitly says 'never estimate or state a price' from them. The purpose is unambiguous and differentiates.

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?

Explicitly provides usage context: 'Call prebook_stay before start_booking' and states that this quote and prebook_stay are the only authoritative price sources. It tells the agent when to use this tool and warns against using alternative listing data for pricing, giving clear decision guidance.

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