iQuota Hotels

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

Annotations already declare this is a mutating, open-world, non-destructive, idempotent operation, so the description is not required to restate that. It adds genuinely new behavior: payment is collected by the property and card details must never be requested, plus the returned booking reference. It does not discuss irreversible effects, cancellation relationship, or failure modes (e.g. sold-out rate), so it stops short of a 5.

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 action, then the guard condition, then the payment rule and return value. No filler or restatement of the tool name; every sentence carries operational weight.

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 supplies the essential return value (booking reference) and covers the critical safety constraint (payment at property, no card details). Combined with annotations that carry the idempotency/destructive profile, an agent has what it needs, though the meaning of rate_key and guest contact fields is left unstated.

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 0% across six parameters, so the schema provides no semantic help. The description does explain the business meaning of traveller_confirmed (it encodes the confirmation checklist) and implies rate_key is the selected room/rate, but guest_name, guest_email, guest_phone and special_requests are never explained. That is more than the schema offers but well short of compensating for the coverage gap.

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 opens with a specific verb and resource ('Confirm a booking') and states the return value (booking reference), which is enough to tell it apart from cancel_booking or get_booking by implication. However, it never explicitly names or contrasts itself with those siblings, so it sits at 'clear but no sibling differentiation' rather than 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?

It gives an explicit, itemized precondition for invocation: only call after the traveller has confirmed hotel, dates, room, total price, cancellation policy and payment terms, and it ties that to setting traveller_confirmed=true. This is a strong when-to-call gate that an agent can apply directly, leaving little 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 declare destructiveHint=true and idempotentHint=true, but they cannot express the dry-run/commit gating that governs correct invocation. The description adds that crucial behavioral context (fee quote first, commit second) plus a human-in-the-loop requirement, which is exactly the value structured fields 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?

Two sentences, front-loaded with the action and then the required protocol. No filler; every clause directs agent behavior.

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, open-world mutation with no output schema, the description covers the critical interaction pattern, and annotations carry the safety profile. It stops short of stating post-cancellation state or error behavior for invalid references.

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 0%, so the description must compensate. It explains the meaning of confirm well through the workflow, but booking_reference and guest_email — both required — are never explained in either the schema or the description. Partial compensation only.

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 ('Cancel a booking') that is unambiguously distinct from siblings like get_booking, book_hotel, and check_rate. An agent can select it 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 an explicit two-phase protocol: call with confirm=false first to obtain the fee, relay it to the traveller, and only re-call with confirm=true if they agree. The condition selecting each mode is spelled out, not implied.

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=false, so the safety profile is covered. The description adds the useful behavioral cue that this is a pre-booking freshness check, but says nothing about whether the rate is locked after the call, what happens if the price changed, or expiry of the rate_key.

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 with the verb, resource, and timing cue; there is no redundant or filler text.

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 simple one-parameter read tool with no output schema, the description covers what it does and when, and annotations cover safety. It is still incomplete regarding the origin/validity of rate_key and what the re-check result conveys (changed price, still available).

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?

There is one required parameter, rate_key, with 0% schema description coverage, and the description never mentions it or where it comes from (presumably a prior search/option result). The description does not compensate for the coverage gap at all.

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 ('Re-check'), resource ('price and availability'), and scope ('of an option'). The timing qualifier 'right before booking' implicitly separates it from search_hotels, but no sibling is named explicitly, so it falls short of the 5-level differentiation.

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 usage context: invoke this 'right before booking' to validate a previously seen option. It does not state when not to use it or name alternatives (e.g. search_hotels for fresh discovery), so it stops at 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the meaningful detail that lookup requires pairing a reference with the guest email, implying email acts as an access check. It says nothing about behavior on no-match, error cases, or what is returned.

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 with no filler; the qualifier 'made through iQuota' is placed before the parameter mention, so the agent gets scope first.

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 two-parameter read-only lookup with annotations covering safety and no output schema, the description is minimally sufficient but omits the return shape and the failure mode when the reference and email don't match, which an agent would benefit from knowing.

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 0%, so the description carries the burden, and it does mention both inputs ('its reference and the guest email'), implying they must correspond. However it adds no format, casing, or matching-rule detail, so it only marginally compensates for the undocumented 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?

States a specific verb and resource ('look up a booking') and scopes it to bookings made through iQuota. It doesn't explicitly distinguish itself from siblings like get_hotel or cancel_booking, but the resource and system qualifier make its domain clear enough to route to.

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?

No when-to-use guidance, no prerequisites beyond the parameters, and no mention of alternatives (e.g., how it differs from search_hotels or when a booking lookup rather than a cancellation flow is appropriate). Usage is only inferable from the tool name and required fields.

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=false, so the safety profile is covered. The description adds genuine context that hotel_code is not required when calling a hotel's own connector, but it says nothing about auth requirements, rate limits, or response shape/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?

Front-loaded with the core purpose, then a single informative enumeration with no filler. The field list is long but earns its place by previewing the response payload. One sentence, no 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?

For a read-only, one-optional-parameter tool with no output schema, the description compensates by enumerating the returned fields. The only real gap is routing guidance versus search_hotels, which the usage line leaves 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 0% for the single optional hotel_code parameter, so the description must compensate. It does explain that hotel_code is unnecessary on a hotel's own connector, which justifies the empty default and clarifies when the parameter matters — meaningful beyond the schema's bare string type.

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 (full details of a hotel) and enumerates the exact payload: description, amenities, photos, location, rooms, check-in times, children policy and payment terms. This clearly separates it from siblings like search_hotels (which lists) and book_hotel (which mutates).

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 detail-fetch step after a search, but no alternative (e.g. search_hotels) is named and no when-not condition is stated. The parenthetical about hotel_code not being needed on a hotel's own connector hints at a specific calling context but is not framed as 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?

Beyond the readOnlyHint annotation, the description adds real behavioral context: results are hotels with selectable options, each option's rate_key expires in 30 minutes, and currency only works 'if the property sells in it'. It does not mention rate limits, auth, or pagination 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?

Purpose is front-loaded and every sentence carries parameter or workflow information with no filler. The middle section is somewhat run-on and awkwardly line-wrapped ('Dates YYYY-MM-DD. adults and children_ages are per room.'), which slightly hurts scanability.

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 nine-parameter search with no output schema, the description covers the essential inputs and sketches the return shape (hotels with options and a rate_key). Gaps remain around rooms/max_total_price semantics and result volume/pagination, but nothing critical to making a valid call 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 0%, so the description must carry the burden; it explains destination formats (city, area, region, hotel name, ISO code), date format YYYY-MM-DD, per-room semantics for adults/children_ages, currency examples, and board values. It omits any explanation of rooms and max_total_price, leaving two of nine parameters undocumented.

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, apartments, villas) and qualifies the scope as 'live availability and prices of directly-contracted' inventory. It also distinguishes itself from the nearby siblings by naming check_rate and book_hotel as the downstream consumers of its rate_key output.

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 routes the agent forward explicitly: options carry a rate_key 'for check_rate and book_hotel', which tells the agent what to do after searching. It also notes destination is 'not needed on a hotel's own connector', hinting at get_hotel usage. However, it never states when NOT to use this tool or how it differs from get_hotel directly.

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