Quub hotel search and booking

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

Annotations declare the safety profile (destructive=true, idempotent=true), but the description adds material context they cannot carry: the refund follows the rate terms, is credited back to the card through Nuitee, and the free-cancellation window is bounded by a deadline. It also discloses the auth blocker (no Quub API key on this connection), which is exactly the kind of precondition an agent needs before invoking a destructive 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 purpose and refund consequence, then constraints, then prerequisites. Five short sentences with little waste, though 'Needs the guest email' is mildly redundant against a required schema field and could be dropped.

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, irreversible cancellation with no output schema, the description covers everything an agent needs: what is refunded, where the money goes, which rates are eligible, who must request it, and that the call is currently blocked pending an API key. Nothing material 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% and both parameters are required, so the schema already documents booking_id and guest_email. The description only restates that the guest email is needed, adding no format, provenance, or edge-case detail beyond what is structured. Baseline 3 is appropriate.

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 ('Cancels a confirmed booking') and narrows the scope with two qualifiers: the rate must be refundable and the booking must have been made with this key. No sibling tool performs cancellation, so the agent can immediately place it in the toolset.

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 gate ('Only call this when the guest asked for it'), an explicit exclusion ('Non-refundable rates cannot be cancelled online'), and routes to the correct alternative tool for the blocking prerequisite ('this connection has none yet: use request_api_key'). When-to-use, when-not-to, and the prerequisite path are all named.

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=true, and the description adds real operational context beyond that: the auth requirement (Quub API key), the fact this connection lacks one, the remediation path (request_api_key), and the dependency on prebook output. It does not contradict the read-only annotation.

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 information, but the middle enumeration of status values is dense and parenthetical-heavy, making it feel like a run-on rather than cleanly structured prose.

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 steps in to describe the returned statuses and fields (pay_url, confirmation number, hotel reference, voucher_url, refund, total, cancellation terms, free cancellation deadline), plus auth and prerequisites. An agent has everything needed to call and interpret it.

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%, but the description adds meaning the schema does not: that the caller needs guest_email OR booking_secret even though the schema marks only booking_id as required, and it ties booking_secret/booking_id back to prebook. This resolves a genuine ambiguity in the required-parameter list.

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: retrieves the status of a booking created by this key, and enumerates the concrete return states (awaiting_payment, confirming, confirmed, outcome_pending, failed/cancelled). This clearly distinguishes it from siblings like get_hotel or prebook.

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 prerequisites (needs guest_email or booking_secret from prebook) and routes to a sibling when the key is missing (use request_api_key). It does not explicitly state when-not-to-use it versus cancel_booking, 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.

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

readOnlyHint=true already establishes the safety profile, so the bar is lower, and the description earns credit by disclosing the shape of what comes back (key_facts, areas with suitability/parking/distances, articles, FAQ, and per-fact source URLs). It still omits error behavior for an unknown slug and any auth expectations, keeping it short of the top mark.

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?

It is a single front-loaded sentence that leads with the resource and then enumerates contents, with no filler or redundancy. The enumeration is long, but because there is no output schema it is doing real work rather than padding.

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 effectively substitutes for one by cataloguing the returned sections and noting each fact carries a source URL. The main remaining gap is failure handling for an invalid slug, which is not covered anywhere.

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?

With a single parameter and 100% schema coverage, the schema already documents slug fully, including its source tool and an example. The description adds nothing about the parameter, 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?

The description makes clear this retrieves a single destination guide's content and enumerates what that content comprises (key facts, areas to stay, articles, FAQ, sources), so the verb+resource is unambiguous. It does not, however, position itself against the obvious sibling list_destinations, which is only referenced inside the schema rather than the description.

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?

There is no explicit when-to-use or when-not-to-use guidance; the only routing hint (the slug comes from list_destinations) lives in the input schema, not the description. An agent must infer that this is the drill-down call after list_destinations, with no stated prerequisite or alternative.

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 and openWorldHint; the description carries the real behavioral burden. It defines what the prices numerically represent (total for the whole stay, one room, in the requested currency, Nuitee as merchant of record, taxes Nuitee collects included) and separates property-paid taxes into taxes_at_property, plus explains the purpose of book_url. This is exactly the context an agent needs before quoting prices.

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?

Information-dense with no filler, and the returned payload is front-loaded before the pricing caveats. The first sentence is an unusually long run-on with nested parenthetical enumerations, which hurts scannability, but every clause carries substantive meaning.

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 fully owns explaining the return shape and does so thoroughly (hotel fields, offer fields, pricing, taxes, book_url). Minor gaps remain: it never says what happens if no dates are passed for availability, and it doesn't point to prebook for continuing the booking flow.

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 seven parameters are already documented, which sets the baseline at 3. The description restates the currency default and the fact that prices are per-room totals, but adds no new syntax or constraint detail for adults, children, dates, or nationality beyond what the schema already 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?

States a specific verb+resource ('One hotel's details') and enumerates the exact fields returned, including room offers when dates are supplied. It is distinguishable in substance from search_hotels and the booking siblings, though it never names an alternative 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 by the conditional clause 'when dates are given, every bookable room for them', which hints at the two operating modes. There is no explicit guidance on when to call this versus search_hotels (to find hotel_id) or prebook (to obtain a booking token), so the agent must infer the workflow.

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=true; the description goes further by disclosing the response shape (slug, name, country, one line, last fact check, guide URL), which matters since there is no output schema. It omits pagination/result-count behavior, but for a small reference list that is a minor gap.

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 with the resource definition front-loaded, then the hotel caveat, then the parameter note. The parenthetical field list is dense but earns its place by standing in for a missing output schema.

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 zero-required-parameter read tool with no output schema, the description covers what is returned, the one optional filter, and the key scope caveat about hotels. Only pagination or ordering behavior is left unspecified.

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. The description adds that q is optional and filters by name or country, but it drops 'slug', which the schema explicitly supports — a small loss of precision rather than added meaning.

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 the resource (destination guides Quub has sourced) and enumerates the returned fields, so the agent knows exactly what this lists versus get_destination_guide (singular fetch). It never states the verb 'list' explicitly, relying on the name/title, but the scope is unmistakable.

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?

'Hotels can be searched anywhere, not only in these' is an explicit exclusion that steers the agent away from treating this as a hotel inventory filter, implicitly routing hotel queries to search_hotels. It stops short of naming the sibling or stating when to prefer get_destination_guide for a single entry.

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 the mutation/idempotency profile, but the description carries much more: nothing is charged by any tool, the booking exists only after payment on Nuitee's form, booking_secret is shown once, price_changed flags repricing, and idempotency_key makes retries safe. These are real behavioral traits beyond the structured hints.

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-loads the core action and return values, then moves to guest-facing instructions, with no filler sentences. It is dense and slightly long, but each clause (repricing, cancellation terms, API key) carries actionable 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?

For a 14-parameter mutation with no output schema, the description adequately explains what is returned (booking_id, booking_secret, total, price_changed, cancellation terms, pay_url) and the auth prerequisite, so an agent has everything needed to call it and act on the result.

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 dates, nationality defaults, currency, and idempotency semantics. The description largely restates the critical constraints (guest name matching the ID, phone with country code, sending an idempotency key) rather than adding new format or edge-case detail, so baseline 3 is appropriate.

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 ('Holds one room ... with the partner for the named guest') and names where the offer_id comes from (search_hotels, get_hotel), which cleanly separates it from those exploration siblings. An agent can identify this as the committing step of the booking flow 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?

Gives clear sequencing context — this follows search_hotels/get_hotel, and the guest pays on pay_url rather than through the tool — plus a concrete fallback (request_api_key) when the connection lacks a key. It never states an explicit when-not or a named alternative for the booking step (e.g., vs cancel_booking), so it stops short of 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 only declare readOnlyHint=false and openWorldHint=true; the description adds the externally visible side effect (an email is sent), the one-time/link-shown-once semantics, how the caller later authenticates with the key, and a commercial consequence (8 percent margin on bookings made with a key). That is substantial behavior beyond the 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?

A single tight paragraph with the core action front-loaded, followed by the follow-up flow, prerequisites, cost implication, and safety constraint in descending priority. No sentence is 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, the description still conveys what happens after the call (email sent, key revealed once to the recipient, not returned here) and the downstream auth format. Minor gaps remain, such as rate limits or delivery failure behavior, but the agent has enough to invoke 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 description coverage is 100%, so both 'email' and 'label' are already documented in the schema ('Where the link goes.', 'A name for the key'). The description only implicitly clarifies that email must be the address owner's, adding little beyond the schema; baseline 3 is appropriate.

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 concrete verb and effect: 'Sends an email with a one-time link to a free Quub API key.' The resource (API key) and mechanism (emailed one-time link) are unambiguous and cannot be confused with any sibling such as search_hotels or prebook.

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 trigger condition explicitly: a key is needed for prebook, get_booking and cancel_booking and raises search limits, naming the exact sibling tools that depend on it. It also gives a consent constraint ('Only send it to an address the person gave you for this'), which functions as a when-not rule.

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 readOnly/openWorld, but the description adds substantial behavioral context beyond them: prices are whole-stay totals for one room, in the requested currency, charged by Nuitee as merchant of record, with Nuitee-collected taxes included and property taxes listed separately. That pricing/merchant semantics materially affects interpretation of results.

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 purpose, then result fields, then pricing semantics. Dense but each clause carries real content; the pricing/merchant paragraph is long but earns its place given there is no output schema.

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 fully enumerates the returned fields (id, name, stars, guest rating, coordinates, area/distance, cheapest room with total, board, refund rule, free-cancellation deadline, offer_id, and booking URLs) plus the pricing basis, leaving nothing essential ambiguous for correct invocation.

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. The description still adds meaning by widening 'place' beyond the schema's examples to city, region, island, airport, or landmark anywhere in the world, and by clarifying that results are capped at limit and ordered via sort (cheapest or best rated).

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+resource+scope: 'Live hotel prices for a place and dates.' It is immediately distinguishable from siblings like get_hotel, list_destinations, and prebook, and it explicitly names two of them in routing roles.

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?

Routes the agent to siblings: slugs come from list_destinations, and the returned offer_id is the input for prebook. This gives clear context for when to use this tool and what to do with its output, though it never states explicit exclusions or when not to use it.

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