hotels

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by stating this is a post-payment verification step and that BOTH booking id and guest email are mandatory, implying a lookup that fails without matching credentials. It does not describe behavior when the email does not match the 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?

Three tight sentences: what it verifies first, prerequisites second, timing third. No filler, and the most decision-relevant content (verb + returned fields) is front-loaded.

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 only two fully documented parameters, an explicit read-only annotation, and no output schema, the description supplies everything needed: it enumerates the returned fields in lieu of an output schema and pins the call to the correct point in the booking workflow.

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; the description goes further by explaining where the values originate (the guest's confirmation) and emphasizing that both are jointly required, which matters for a lookup keyed on a pair rather than a single id.

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 (Verify) and resource (a completed booking) and enumerates exactly what is retrieved: confirmation status, hotel confirmation code, stay and price. It also names the sibling it follows (prepare_booking), so an agent can place it in the booking flow 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 an explicit trigger and sequencing: 'Use after the human pays via a prepare_booking link,' plus the prerequisite that both identifiers come from the guest's confirmation. It lacks an explicit when-not or a named alternative for other booking states (e.g. pre-payment lookups), which keeps it short of a 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 establish this is a safe read (readOnlyHint) and not open-world. The description adds real behavioral context beyond them: the calendar is editorial, geographically limited to Dubai/Abu Dhabi with Goa explicitly absent, and entries carry suggested book-by deadlines. No return format detail, but that is minor for an annotation-covered read tool.

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 resource and its scope, and dense with useful specifics (event types, book-by deadlines). The parenthetical scope caveat is long, but every clause carries information rather than 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 one-parameter read tool with no output schema, the description supplies enough: what the calendar contains, what it covers, and what to do with it. Return-value shape is left implicit, which is acceptable given the lack of an output schema.

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% and the single city parameter carries an enum and its own description, so the schema does the semantic work. The description's 'UAE only — Dubai and Abu Dhabi' corroborates the enum values but adds no format or default guidance beyond what the schema states.

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 resource ('Fostay's editorial demand calendar') with a clear function: upcoming date windows where demand spikes, each with a book-by deadline. Scope is precisely bounded (UAE only — Dubai and Abu Dhabi; Goa excluded), which helps an agent tell it apart from siblings. It does not explicitly name which sibling it is not, so it stops just 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?

Gives concrete usage context: 'Use it to warn users about expensive dates or find event stays.' That is a clear trigger condition an agent can act on. It names no exclusions or explicit alternatives (e.g., when_to_go), so it falls short of 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 a read-only, open-world operation, so the safety profile is covered; the description nonetheless adds substantive behavior: currency of the total depends on destination, Goa's total_all_in includes GST, hotel-collected portions are itemised separately in collected_by_hotel_at_checkin, and prices are refundability-aware with exact free-cancellation deadlines. What's missing is any hint about freshness/latency of 'live' data or result variability (rate plans, sold-out cases), which for a price-quoting tool would matter.

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 what is returned and the price semantics first, then the currency/GST caveats, then booking_url. Dense but every sentence carries information; the parenthetical field names are slightly verbose but functional.

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, the description usefully names and interprets the key returned fields (total_all_in, collected_by_hotel_at_checkin, board, refundability, booking_url), which is the main burden here. Remaining gaps are minor but real: nothing about empty/sold-out responses, data freshness, or how many offers typically come back for a date range.

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 all six parameters are already documented, including the currency enum, defaults and the children-ages guidance. The description mostly restates that (INR for Goa, AED for Dubai/Abu Dhabi, or the currency you pass) rather than adding new parameter-level meaning, so the baseline 3 applies; its genuinely new material concerns output fields, not inputs.

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 with scope: 'Live bookable room offers for one hotel and stay dates', and enumerates what comes back (all-in price, board, refundability, cancellation deadlines). It doesn't name a sibling tool to contrast with, so an agent must infer the boundary against search_stays/prepare_booking rather than being told.

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 by 'for one hotel and stay dates' and by the note that booking_url completes the booking on fostay.com, which hints this is the pre-booking rate lookup. There is no explicit when-to-use/when-not, and no mention of choosing this over prepare_booking or first calling search_stays to obtain a hotel_id (that link only appears in the schema).

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 cover readOnly/idempotent/destructive/openWorld; the description goes well beyond them by disclosing that the hold is a real prebook with a locked price, that the payment_url is opened by the human, and that the agent never handles card details. It also warns the return may carry a different final price plus change warnings.

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 dense sentences, front-loaded with the core behavior and the payment_url return, then prerequisites, then edge-case handling. Every sentence carries information relevant to correct invocation; only the double-dash phrasing adds slight friction.

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?

There is no output schema, so the description carries the return-value burden and does so fully (payment_url, final price, change warnings). For a 6-parameter mutation with openWorld semantics, the operational guidance about confirming details and relaying price changes closes the remaining gaps.

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%, so the description must compensate. It conveys that guest name/email are required and that the offer is the 'chosen offer' (tying back to get_live_rates), but it says nothing about agent_name or guest_phone, leaving those parameters to the schema alone.

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 scope: holds the offer, registers guest details, returns a payment_url, while explicitly excluding payment handling. This lets an agent distinguish it from get_live_rates (which supplies offer_id) and booking_status (which likely tracks the result) 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 an explicit precondition — confirm the guest's name and email with the user before calling — and a post-call obligation: relay any price change before sending the user to pay. It lacks an explicit when-not or a named alternative sibling, but the context is clear enough to route correctly.

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 and openWorldHint, so safety is covered. The description adds substantial behavior beyond that: curated edit returned first for Dubai/Abu Dhabi, ~2,000 catalog matches, Goa's review-based ordering, hostels/homestays surfacing only on name search, and inclusion of a fostay_url for human follow-up.

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 primary action and scope, then the branch-specific behavior. Every sentence carries distinct information; the three-city breakdown is dense but each clause is load-bearing.

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, the description carries return-value burden and does so by describing the result composition (curated edit vs catalog) and the fostay_url. Pagination/limit behavior and the min_rating filter's effect are left to the schema, which is acceptable at full coverage.

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. However the description adds meaning beyond the schema by disclosing that the query parameter changes result composition (hostels/homestays only when searched by name) and that area optionally narrows Goa results.

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 (search) plus resource (hotels/stays) and bounded scope (Dubai, Abu Dhabi, Goa), then differentiates itself from siblings by routing price lookups to get_live_rates. An agent can distinguish this from booking_status, demand_calendar or prepare_booking 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?

Explicitly names get_live_rates as the alternative for prices, which is concrete routing. It also explains per-city result behavior, but does not state outright when not to use this tool (e.g. for booking or availability) or any prerequisites.

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 and openWorldHint, so the bar is lower; the description adds real context: 2-night Fri–Sun window, roughly 6–8 weekend horizon depending on mode, and that results are ordered cheapest first. It doesn't describe error or empty-result behavior, but the pricing scope and ordering are well disclosed.

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 dense sentences, front-loaded with the core action and ending with the ordering guarantee. No filler or repetition of the title.

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 read-only pricing query with no output schema, the description covers scope, both input modes, time horizon, and sort order. Minor gap is what the returned price entries actually contain, but the essential calling information is present.

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, and the description goes further by explaining the hotel_id vs city relationship (city is used when hotel_id is omitted) rather than just restating field names. Currency behavior is left to the schema, which already covers it.

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?

Specific verb (prices) plus resource (upcoming Fri–Sun 2-night weekends) and an explicit goal (find cheapest times to stay). An agent can distinguish it from get_live_rates and search_stays 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?

Clearly states the two modes: pass hotel_id for one hotel (~8 weekends) or a city to compare curated stays (~6 weekends), including the specific cities. It doesn't explicitly exclude sibling tools like get_live_rates, but the conditions for each mode are concrete.

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