PriceWin

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds what those annotations cannot: that the action is irreversible, that it triggers a refund, and that token validation failures (missing/expired/used) cause rejection. That is material behavior beyond the 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?

Three sentences, front-loaded with the irreversibility and role in the flow, then prerequisites, then the pointer to the policy sibling. No filler or restated field names.

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 destructive three-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs: ordering, prerequisites, failure modes, and reversibility. Return-value details are correctly omitted since an output schema exists.

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 100%, so the baseline is 3, but the description adds lifecycle semantics the schema only hints at: the token is single-use, is delivered by email via request_cancel_token, and is rejected if expired or consumed. These constraints meaningfully shape invocation beyond the field descriptions.

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 ('cancels'), the resource ('a booking'), the side effect ('starts any refund due'), and its position in the two-step flow. An agent can distinguish it from request_cancel_token and get_cancellation_policy 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?

It says this is the second of two steps, names the prerequisite producer (request_cancel_token), describes the required input provenance (emailed token), and identifies the sibling (get_cancellation_policy) for refund terms. Rejection conditions for the token also act as explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that this is a status-observation tool returning one of three discrete states, but it says nothing about statuses changing over time, whether re-polling is expected, or latency of hotel confirmation.

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?

A single sentence that front-loads the verb and resource, then qualifies with the enumeration of states and the key source. No filler or redundancy.

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-value structure need not be explained, and the description still usefully names the three possible states. For a read-only lookup it is nearly complete; only polling/timing behavior is left unaddressed, which is a minor gap.

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 both parameters (confirmationCode with example, language enum) are fully documented in the schema. The description only restates the provenance of confirmationCode, which the schema description already conveys, adding no syntax or format detail beyond it. Baseline 3 applies.

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 (returns) and resource (current status of a booking request), enumerates the possible states (waiting for the hotel, confirmed, cancelled), and ties the key to its producer (request_booking). An agent can distinguish it from cancel_booking or the search tools 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?

The phrase 'by the confirmation code request_booking returned' establishes the precondition that a booking must already exist, which is clear usage context. It stops short of explicitly naming alternatives or stating when-not to use it (e.g. don't call before requesting a booking), so it isn't a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's added behavior is that the exact free-cancellation deadline is computed from the check-in date, which is useful, but much of the remaining text restates return fields already covered by the output schema.

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?

A single front-loaded sentence that leads with the action and resource, then lists outputs, then input provenance. It is long but each clause carries information; no filler sentences.

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 an output schema present and annotations covering safety, the description only needs to establish scope and inputs, which it does fully: what is returned, for which entity, and where the required ids come from. Nothing an agent needs to invoke it correctly is missing.

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 five parameters, including the provenance of propertyId and ratePlanId and the purpose of checkInDate. The description reinforces the two id parameters but adds no syntax or format detail beyond the schema; baseline 3 applies.

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 ('Returns the cancellation terms for one rate plan at an OpenTravel partner hotel') and enumerates the concrete outputs: refundability, free-cancellation window, refund percentage, summary, and computed deadline. That level of specificity clearly separates it from siblings like get_hotel_detail or cancel_booking.

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 clear provenance for two of the three required inputs ('Takes the propertyId and the ratePlanId from get_hotel_detail'), which tells the agent when in a workflow this call fits. It stops short of stating exclusions or naming alternatives (e.g., that this is not the tool for actually cancelling), so it is clear context without routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the nature of the content returned (live rates, per-room rate plans), but says nothing about latency, rate freshness, failure modes when a name/city lookup is ambiguous, or whether the pricing is cacheable — so it adds only modest context beyond 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?

Three sentences, zero filler, front-loaded with what the tool returns before moving to identification inputs and then the sibling boundary. Every sentence earns its place.

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 an output schema present and 100% parameter coverage, the description needn't restate return fields, and it covers identification, data scope and one alternative. The only gap is an explicit contrast against get_ota_hotel_detail, a name-adjacent sibling an agent could easily confuse with this one.

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 100%, so the schema carries the per-field detail and baseline would be 3. The description goes slightly further by stating the resolution pairing ('a hotel name plus city') and the provenance of propertyId (search results with source 'OPENTRAVEL_DIRECT'), which clarifies a real dependency the schema only encodes per-field.

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 precise verb+resource+scope: prices and availability for one OpenTravel direct-listed hotel over a date range, plus the returned payload (photos, amenities, room types with rate plans and total prices). It also implicitly carves out the sibling boundary by specifying 'OpenTravel direct-listed', which distinguishes it from get_ota_hotel_detail.

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 clear entry conditions: take propertyId from search results (source 'OPENTRAVEL_DIRECT'), or resolve by hotelName plus city for a known direct listing. It names get_hotel_info as the static-facts alternative, but never explicitly contrasts with get_ota_hotel_detail or search_hotels_live, leaving one sibling boundary to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: this endpoint is date-agnostic, deliberately carries no prices or availability, and is scoped to 'direct-listed' properties. It stops short of covering rate limits or error behaviour, but that is minor given the annotation coverage.

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?

One dense paragraph, front-loaded with the defining trait (no dates needed) followed by the returned-data inventory and the sibling comparison. The long enumerated clause list is justified by the number of distinct facts returned, though it could be tightened slightly.

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 no further explanation, yet the description still tells the agent what categories of data come back. Combined with the date-agnostic scope, sibling routing and identifier provenance, nothing needed to call this tool correctly is missing.

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 propertyId, language and queryText; baseline is 3. The description reinforces where propertyId comes from (search results) but adds nothing about the language or queryText parameters, so it does not exceed what the schema provides.

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?

Names the specific resource (static facts about an OpenTravel direct-listed hotel) and enumerates exactly which fields are returned — photos, description, address, facilities, check-in/out times, cancellation policy, room details. It explicitly distinguishes itself from the sibling get_hotel_detail by scope (no dates, no prices, no availability).

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?

States the selection condition outright: use this when no check-in/check-out date is needed, and use get_hotel_detail instead when a specific date range's prices and availability are required. It also names the source of the required identifier (the propertyId UUID from search results), so the agent knows where to get the input.

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

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

Beyond the annotations (which only mark openWorldHint=true and destructiveHint=false), the description discloses that the fetch is live, can take about two minutes, and may return not-found under heavy load. That is meaningful operational context. It stops short of covering auth or why readOnlyHint is false, so it is strong but not exhaustive.

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?

Content is front-loaded with what the tool returns and its scope distinction, then resolution mechanics, alternatives, and latency. Every sentence carries information, though the sentence packing several ideas plus the OpenTravel aside is dense enough that it is not maximally tight.

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?

Despite no output schema and nine parameters, the description covers the return payload, the naming/resolution requirement, the URL shortcut, sibling routing, and the latency/failure behavior. An agent has everything needed to call it 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 coverage is 100%, so baseline is 3, but the description adds relational meaning: the hotel name is resolved through the city's listings (so hotelName and city are used together), and propertyUrl bypasses that lookup. This clarifies parameter interaction beyond the per-field schema text.

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 names a specific verb+resource (fetch full hotel detail for one named hotel over a date range) and enumerates the returned payload (rooms, live prices, facilities, photos, reviews). It explicitly differentiates scope from the sibling 'search_hotels_live' (city-wide) so the agent can route without opening either 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?

It states when to use this tool (requests about a single hotel) and contrasts it against both a sibling for city searches (search_hotels_live) and a sibling for OpenTravel direct listings (get_hotel_detail). It also tells the agent how to skip the name lookup via a Booking.com URL from an earlier result.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: results may be partial mid-search and a status field terminates at 'completed' or 'failed'. This is the kind of polling-lifecycle detail annotations cannot express.

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?

Two tightly written sentences with no filler. The payload contents are front-loaded and the partial/status caveat follows immediately, which is exactly the order an agent needs.

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 single-parameter read tool with annotations and an output schema, the description is nearly complete: it covers the source of the session, the payload, and terminal statuses. The only omission is relation to the generic poll_search_results sibling, which an agent might otherwise confuse it with.

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?

Only one parameter, and schema description coverage is 100% with the sessionId field already documented as coming from search_flights_live; the description repeats that origin without adding format or validation detail. Baseline 3 applies when the schema does the heavy lifting.

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 (returns/polls) and resource (flight search session results), and names the sibling that creates the session, search_flights_live. It does not distinguish itself from the near-identical sibling poll_search_results, so it stops short of a 5.

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: the description notes results may be partial while the search runs and that status flips to 'completed'/'failed' when done, which tells the agent to keep polling. However, there is no explicit when-to-use versus poll_search_results, and no exclusion or prerequisite (e.g. session must exist) stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: results may be partial mid-search and a status field flips to 'completed' once every source has responded — essential for an agent deciding whether to re-poll.

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 sentences, no filler, and the highest-value information (what it returns and the session linkage) is front-loaded. The partial-results caveat follows immediately behind it.

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-value documentation is not required; the description nonetheless sketches the shape. The async/polling semantics, the prerequisite tool, and the downstream consumers are all covered, leaving nothing an agent needs to call this 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% across all 9 parameters, so the schema already documents sessionId provenance, pagination, limit, and the filter overrides. The description adds essentially no parameter-level detail beyond what the schema states, so the baseline 3 applies.

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 ('Returns the current results of a hotel search session') and anchors it to the sibling that creates the session (search_hotels_live). It even enumerates the payload shape — hotels with per-source prices plus OpenTravel direct listings — so an agent can distinguish it from search_hotels_live without opening either 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?

Clearly implies the workflow: call after search_hotels_live, poll while results are partial, expect status 'completed' when all sources answer. It also names the downstream consumers (get_hotel_detail, get_hotel_info) via propertyId. It doesn't state explicit exclusions or a polling interval/backoff, so it falls short of a full 5.

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

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

With annotations only covering safety flags (readOnly=false, destructive=false, openWorld=true), the description carries real behavioral weight: no charge, no room held, hotel confirms by email, guest pays at property, no payment step now or later, missing-field handling that may open a widget form, and the exception where some properties require payment at booking.

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?

Five sentences, front-loaded with the single most important fact (nothing is charged, no room held) before the input provenance and the payment exception. Slight redundancy between 'Nothing is charged and no room is held' and 'There is no payment step, now or later', which costs a point.

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 13 parameters, an output schema that already documents the confirmation code, and annotations that only cover safety, the description supplies the remaining context an agent needs: the non-committal nature of the call, fallback behavior for missing guest details, and the payment-at-booking exception.

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 baseline is 3, but the description adds provenance the schema does not: which fields are sourced from get_hotel_detail versus from the guest, and that guestEmail cannot be changed after the request is sent. It does not explain totalAmount/currency sourcing in more depth than the schema already does.

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+resource ('Sends a booking request for a room at an OpenTravel partner hotel') and immediately scopes it as a non-binding request, which cleanly separates it from cancel_booking, check_booking_status and the get_hotel_detail family.

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?

Clearly states where the inputs come from ('Takes the room and rate from get_hotel_detail and the guest's name, phone number and email') and what happens when they are missing, which is strong usage context. It stops short of naming an explicit alternative or a when-not-to-use condition, so it is not a full 5.

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

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

Annotations give destructiveHint=false and openWorldHint=true but say nothing about side effects, timing, or token lifetime; the description fills that gap by disclosing the email side effect, the 24-hour expiry, single-use semantics, and that no charge or refund occurs. This is exactly the extra context 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?

Four short sentences, front-loaded with the step-1-of-2 framing, then preconditions, then the no-side-effect guarantee, then token lifetime and the handoff. No sentence is redundant.

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?

Output schema exists so return values need not be described, and the description covers the workflow position, prerequisites, side effects, token lifetime, and the next step. Nothing an agent needs to invoke this correctly is missing.

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% and both parameters are documented in the schema (guestEmail must match the primary guest, confirmationCode is an 8-char code). The description restates the email-must-match rule and adds no format or syntax detail beyond the schema, so baseline 3 applies.

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?

Names a specific verb and resource (request a cancellation token) and frames itself explicitly as step 1 of a 2-step cancellation flow, which separates it cleanly from the sibling cancel_booking that performs the actual cancellation.

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?

States the precondition (confirmation code plus the matching booking email) and names the follow-up tool that consumes the token, so the agent knows both when to call this and what to call next. The 'nothing is cancelled by this step' clause further clarifies it is the entry point, not the completion.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, and the description adds genuinely non-redundant behavior: it returns a session ID for an asynchronous poll cycle, names the upstream fare providers, and explains that missing route/date yields a clarifying question rather than an error. No contradiction with annotations.

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?

Four sentences, front-loaded with the action and scope, then the async contract and the missing-input fallback. Dense with no filler, though the provider list is marketing-adjacent detail that an agent does not strictly need to select the tool.

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 fields need not be explained, and the description still covers the key async handoff to poll_flight_results plus the missing-input behavior. Given 8 mostly-optional parameters and a mutation-style session creation, it is complete enough; only the absence of guidance on optional inputs like cabin/adults in prose keeps it from a 5.

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 every parameter (origin, destination, dates, cabin, adults, language, queryText) is already documented with format patterns and defaults in the schema. The description restates the IATA 3-letter convention and one-way/return semantics but adds no format or constraint detail beyond the structured fields, so the baseline 3 applies.

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 ('Starts a live flight search for a route and date, one-way or return') and explicitly distinguishes itself from the sibling that completes the job ('poll_flight_results returns the results'). An agent can separate it from search_hotels_live and the poll_* tools without opening a 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 clear routing to the follow-up tool (poll_flight_results) and describes the degenerate case where required inputs are absent ('the result is a question for the user instead of a search'). It does not state exclusions such as when a cached/batch search would be preferable, so it falls short of a full when/when-not treatment.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true. The description adds rich behavioral detail beyond them: an asynchronous session-ID model requiring polling, multi-provider price aggregation (Agoda/Booking.com/Traveloka/direct partner rates), the default party of 2 adults in 1 room with defaulting flagged in the result, and the fallback of returning a question rather than a search when city or dates are missing.

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 core action and kept to a handful of dense sentences; each sentence carries distinct information (purpose, providers, async polling, filters, party defaults, missing-input behavior). Slightly longer than strictly needed but with no 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?

For a 13-parameter tool with an output schema, the description covers the essential behavior: the async session/polling model, provider sources, defaulting and its flagging, and edge-case handling for missing city/dates. Return values are delegated to the output schema, which is appropriate, leaving only minor unstated details.

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 each parameter (baseline 3). The description adds cross-parameter semantics the schema does not: filters narrow by hotel name/area/total price, the party defaults to 2 adults/1 room and defaulting is flagged in the output, and missing city/dates produce a clarifying question — meaningful value above the schema text.

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 ('Starts a live hotel search') with scope ('for a city and date range'), and distinguishes itself from siblings by naming poll_search_results as the companion for results. An agent can identify it as the hotel counterpart to search_flights_live 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?

The description gives clear workflow context: start a search, then poll_search_results to retrieve arriving results, and states what happens when city/dates are omitted (the result asks the user). It does not explicitly contrast against search_flights_live or get_hotel_detail, so the alternative-selection guidance is implied rather than stated.

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