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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds provenance (Fostay editorial data, predictive rather than live) and the city scope, but says nothing about refresh cadence, how far ahead windows are covered, or return format/pagination.

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 sentences, front-loaded with the resource definition followed by the use case. The parenthetical event list is slightly listy but each item earns its place by making the calendar's contents concrete.

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 does the work of explaining returns: date windows, spike/sell-out predictions, and book-by deadlines. It lacks only coverage-window and pagination details, which are minor for a one-optional-parameter read tool.

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% for the single optional city enum, so the schema already carries the parameter semantics. The description's mention of Dubai and Abu Dhabi aligns with the enum but adds no filtering syntax, default behavior, or output-shaping 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?

The description names a concrete resource (an editorial demand calendar of Dubai/Abu Dhabi hotel spike and sell-out windows) with example triggers (GITEX, F1, NYE, Eid, school breaks) and the payload it carries (a suggested book-by deadline). It is clearly distinct from sibling get_live_rates, which supplies live pricing rather than curated forecasts.

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 gives an explicit use case — warn users about expensive dates or find event stays — which tells the agent the right situation to reach for it. It stops short of naming when not to use it or pointing at a sibling such as when_to_go for alternative timing advice, so it is clear context without exclusions.

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 cover safety (readOnlyHint=true) and scope (openWorldHint=true), so the bar is lower. The description adds real value beyond them: what the offer set contains (all-in AED price, board type, refundability, exact free-cancellation deadlines) and that booking_url is a human-facing handoff to fostay.com rather than an API action. It does not discuss rate volatility, caching, or error/empty-result 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?

Two tight sentences with no filler; the returned-offer content is front-loaded before the booking_url handoff detail. Every clause carries information.

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 must convey what comes back, and it does list the key return fields plus the booking_url purpose. It leaves minor gaps — number/ordering of offers, currency handling, and failure modes — but is sufficient for an agent to call and interpret the tool.

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 the schema itself carries strong parameter guidance (child ages, date formats, hotel_id source), so the baseline of 3 applies. The description only echoes currency (AED) and board/refundability concepts without adding syntax or semantics beyond the schema.

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 gives a specific resource (live bookable room offers) scoped to one hotel and stay dates, and enumerates the returned attributes (all-in price, board, refundability, cancellation deadlines). It implicitly separates itself from search_stays by requiring a single hotel_id, but never names or contrasts a sibling explicitly.

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 only implied: an agent can infer this is the pricing/availability step after obtaining a hotel_id from search_stays, and the schema notes the id source. There is no explicit when-to-use, when-not-to-use, or mention of the alternative tools (prepare_booking, when_to_go, demand_calendar).

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=true and openWorldHint=true, so safety is covered. The description adds real behavioral value beyond that: the two-tier result ordering (8 curated flagship stays first, then ~2,000 catalog matches) and the presence of a fostay_url for human viewing/booking. It stops short of describing pagination or how the curated tier is selected.

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 short sentences, zero filler, and the most decision-relevant facts (what it searches, the two-tier result shape, and the pricing alternative) are front-loaded. 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?

There is no output schema, and the description compensates well by describing the return composition and the fostay_url. For a simple 4-parameter search tool this is nearly complete; only pagination/curated-tier selection mechanics are left implicit.

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 city enum, limit bounds, query filter and min_rating scale are all already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, 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 ('Search hotels in Dubai or Abu Dhabi') and immediately scopes the domain to two named cities. It also distinguishes itself from the sibling get_live_rates by naming it, so an agent can route correctly without opening schemas.

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 redirects pricing queries to get_live_rates, which is a genuine alternative and prevents misuse. It does not state when-not to use this tool or how it relates to siblings like prepare_booking or booking_status, 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 already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior: 2-night Fri–Sun windows, ~8 vs ~6 weekend scope depending on mode, and results sorted cheapest-first. Rate limits and pricing freshness are not mentioned.

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 sentences, zero waste: the core action and the hotel_id/city branching are front-loaded, and no sentence merely restates the title or name.

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 does enough by stating the result ordering and the volume of weekends covered. It could say more about what each priced weekend entry contains, but nothing needed to invoke the 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains the trade-off between hotel_id (one hotel, ~8 weekends) and city (Fostay curated stays, ~6 weekends). That is more than the schema's terse 'used when hotel_id is omitted'.

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 (prices) and resource (upcoming Fri–Sun weekends) plus the goal (find cheapest times to stay), which no sibling like get_live_rates or demand_calendar claims. An agent can tell this is a flexible-date price scan rather than a single-date lookup.

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 describes the two invocation modes: pass hotel_id for one property across ~8 weekends, or a city to compare curated stays across ~6 weekends. It does not name or exclude alternative sibling tools for other date-range questions, so it stops short of full when/when-not guidance.

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