GetMyHotels

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

Annotations declare readOnlyHint=false and destructiveHint=false, indicating a non-read, non-destructive mutation. The description adds that the operation adds an item to a trip on a day, but does not disclose side effects, permissions, or limitations. With annotations covering the basics, the description adds marginal behavioral context.

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?

Single sentence, no filler, front-loaded with purpose and examples. Every word contributes value.

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?

The tool has 6 parameters (4 required) and no output schema. The description covers the core action but omits return value (e.g., response containing the created item) and error conditions. For a simple addition tool, it is adequate but not fully complete.

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?

The schema covers all 6 parameters with descriptions (100% coverage). The description repeats 'on a given day' and implicitly includes item types via examples, but adds no new meaning beyond the schema. Baseline 3 is appropriate as the schema already 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?

The description clearly states the verb 'Add', the resource 'item to a saved trip', and lists examples (hotel, flight, activity). It distinguishes itself from siblings like save_trip and list_trips by narrowing to adding items.

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 implies usage for adding various item types to a trip on a specific day, but does not provide explicit when-to-use or when-not-to-use guidance, nor mention alternatives. Given the uniqueness of the tool among siblings, the lack of explicit differentiation is acceptable but not perfect.

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 indicate destructive hint; description adds that cancellation 'may be irreversible and can trigger a refund per policy', which provides additional behavioral context beyond 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?

Two efficient, front-loaded sentences that convey purpose, prerequisite, and consequences without unnecessary words.

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 the tool's simplicity, full schema coverage, and annotations, the description covers all necessary aspects: purpose, prerequisite, and effects. No output schema needed.

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?

Input schema has 100% coverage; description does not add new parameter details beyond what schema provides. However, it references the verification code source, which adds some context.

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?

Description clearly states 'cancel one of the signed-in user's bookings', specifying the action and scope. It is distinct from siblings like 'modify_booking' and 'request_booking_action_code'.

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?

Description explicitly requires the 6-digit verification code from 'request_booking_action_code', providing a clear prerequisite. It does not state when not to use, but context is sufficient.

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 provide readOnlyHint=false and destructiveHint=true, so the description correctly adds context beyond them: the card is not charged, the guest pays on the hosted page, and user confirmation is required beforehand. It does not disclose possible downstream effects such as holds or expiry of the checkout session, but the disclosed behavior is materially useful.

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?

The description is three sentences and front-loads the primary purpose and output before adding safety and prerequisite context. Every sentence earns its place, with no redundant filler or restating of the tool 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?

Despite having no output schema, the description clearly states that the return value is a getmyhotels.com payment URL. The highly detailed input schema covers parameter relationships such as ref versus supplierCode/supplierHotelId. The main missing context is how this checkout differs from create_one_click_checkout, but the critical confirmation and quote-first steps are 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?

The input schema has 100% description coverage and already includes crucial parameter guidance, including the warning to use grandTotal verbatim and not multiply by nights. The description mostly repeats or summarizes this schema-level detail rather than adding new parameter meaning, so a baseline score of 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?

The description states a specific verb and resource: "Create a secure checkout for a chosen hotel room" and names the concrete output: a getmyhotels.com URL. It clearly distinguishes this from the quote sibling by noting it creates the payment page rather than quoting a price, but it does not differentiate itself from the closely named sibling create_one_click_checkout.

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 explicit preconditions: "Confirm the hotel, room, dates, and price with the user before calling" and "Call get_checkout_quote first to confirm the live price." It also clarifies what the tool does not do ("does NOT charge the card"), giving the agent clear context for when it is appropriate to invoke.

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?

The description adds important behavioral context beyond the annotations by stating it does NOT charge the card and that the user confirms on the hosted page. However, with `destructiveHint: true` and no output schema, it does not disclose potential side effects like reservation holds, expiry of the generated URL, or whether a checkout record is immediately created.

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?

The description is three concise sentences with no filler. The core purpose is front-loaded, followed by the critical no-charge clarification and the necessary prerequisite/confirmation steps.

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?

The description covers the essential workflow: signed-in user, saved card, return URL, no immediate charge, and user confirmation. Since there is no output schema, the mention of the returned getmyhotels.com URL is valuable, though more detail about URL expiry or follow-up steps would make it fully complete.

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 parameters are already well documented. The description reinforces the source for `savedPaymentMethodPublicId` and the need to confirm price, but does not add much semantic meaning beyond the structured 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 names a specific action and resource: create a one-click checkout with a saved card and return a hosted confirmation/payment URL. It clearly differentiates from sibling `create_checkout` by emphasizing the saved-card and one-click behavior.

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 provides actionable context: the user must be signed in, have a saved card, and the agent should obtain `savedPaymentMethodPublicId` from `list_payment_methods`. It also instructs to confirm hotel, room, dates, and price with the user first, which is strong usage guidance, though it does not explicitly name alternative tools or 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=true, so the tool's safety and openness are clear. The description adds context about the return format (id, title, text, url, metadata), which is helpful but does not elaborate on side effects, authentication needs, or rate limits. The description is consistent with annotations, so no contradiction.

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?

The description is two sentences, front-loading the purpose and return format. Every word earns its place; there is no fluff or redundancy. It is an example of efficient communication.

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 that the tool has a single parameter, annotations for read-only and open-world behavior, and no output schema, the description covers the essential return fields. It lacks information about possible errors or edge cases, but for a simple fetch tool with well-documented input, it is largely complete.

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%, meaning the parameter 'id' is fully described in the schema. The tool description repeats this information (id from search results or bk_-prefixed) without adding new meaning. Since the schema already carries the full burden, the description adds no extra value for this dimension.

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?

Description clearly states the tool fetches a full record for either a search result id (hotel) or a booking reference. The verb 'Fetch' and specific resource types make the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'get_booking' or 'get_hotel_details', which might overlap in functionality.

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 implies when to use the tool (when you have a search id or booking ref) but does not provide explicit guidance on when not to use it or mention alternatives. For a tool that seems to combine hotel and booking fetching, it would benefit from stating that it is a unified alternative to separate tools.

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, so the description does not need to repeat safety. It adds value by detailing the return fields (status, hotel, dates, guest details), aligning with the read-only nature.

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 primary purpose, no wasted words. Every sentence conveys essential 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?

Even without an output schema, the description specifies the returned data types (status, hotel, dates, guest details). It does not cover error cases, but for a lookup tool this is adequate.

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 description explains that the bookingToken comes from the confirmation email/URL, adding practical context beyond the schema's definition.

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 uses a specific verb 'Look up' and identifies the exact resource 'hotel booking by its management token'. It also lists the returned data (status, hotel, dates, guest details), which distinguishes it from siblings like 'get_my_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?

The description clearly states the required input (management token from confirmation email). It does not explicitly exclude other scenarios or mention alternatives, but the context is sufficient for correct use.

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 the description's 'no booking, no charge' reinforces the safety profile. It adds useful behavioral context: the tool performs a live re-price against the supplier, returns an authoritative grand total, a `rateValidUntil` timestamp, and taxes/fees. It does not detail failure modes or rate limits, but the key behavioral traits are 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?

The description is two sentences with no filler. The core action and safety guarantee are front-loaded, and the return value summary is compact. Every clause 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?

For a read-only re-pricing tool with 14 parameters and no output schema, the description covers the essential context: what it does, what it returns, and where inputs come from. It does not explain the `ref` vs `supplierCode`+`supplierHotelId` alternative, but the schema already documents that. The lack of an output schema is partially compensated by the description listing the key return fields.

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 14 parameters. The description adds value by explaining the purpose of `totalPrice` ('used to detect price changes') and clarifying that `offerRef` comes from `get_rooms`. It also clarifies that `totalPrice` is the total for the whole stay, not a nightly rate, which is critical for correct invocation. This goes beyond the schema's own description.

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 states a specific verb ('re-price'), a specific resource ('a specific room live against the supplier'), and the context ('before checkout'). It also explicitly distinguishes itself from booking/charging ('no booking, no charge') and names the source of inputs (`get_rooms`). This clearly differentiates it from siblings like `create_checkout` and `get_rooms`.

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 clearly indicates when to use this tool: before checkout to re-price a room, and it references `get_rooms` for the `offerRef` and price/currency. It does not explicitly state when NOT to use it or name alternatives like `create_checkout`, but the context is clear enough for an agent to select it appropriately.

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 the description confirms read-only behavior by describing it as 'Get... details'. It adds behavioral context by noting the identification requirement from a previous search, which is valuable. No contradictions.

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?

The description is a single clear sentence with essential information front-loaded. No unnecessary words 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?

Despite no output schema, the description lists returned data (description, amenities, photos, policies, location). Annotations provide readOnlyHint and openWorldHint. It lacks mention of error conditions or rate limits, but for a simple retrieval tool, this is mostly complete.

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% with each parameter described. The description adds minimal extra meaning beyond explaining relationships (ref from search, alternative usage). Baseline 3 is appropriate as the schema already covers parameter semantics.

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 clearly states the tool retrieves full property details for a hotel, listing specific data (description, amenities, photos, policies, location) and identifying the hotel by 'ref' from search_hotels or alternative supplier codes. This distinguishes it from siblings like search_hotels (which returns a list) and get_rooms (likely room-specific).

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 explicitly says to use the 'ref' from search_hotels or supplierCode+supplierHotelId, implying this tool is for fetching details after a search. It provides clear context on how to invoke it but does not state when not to use it or compare with alternatives.

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?

The readOnlyHint annotation already communicates safety. The description adds that it returns 'full details' and uses a public ID, but does not disclose error behavior (e.g., 404 if booking not found) or rate limits. Given the annotation, the description is minimally supplementary.

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 conveys the tool's purpose without any extraneous information. It is front-loaded and efficient.

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 no output schema, the description could be more specific about what 'full details' includes. For a simple read tool it is adequate, but the output structure is left ambiguous.

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% with a clear description of 'publicId'. The description does not add any additional parameter semantics beyond what the schema already provides, so it meets the baseline for high coverage.

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 clearly states the tool gets full details of a booking for the signed-in user, using the booking's public ID. This distinguishes it from siblings like list_my_bookings (list vs. single) and get_booking (any user vs. own).

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 mentions 'signed-in user' scoping, which helps decide between this and get_booking. However, it does not explicitly say when not to use it or name alternatives, leaving some inference to the agent.

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?

The annotations already mark this as read-only and open-world. The description adds useful context beyond that: single-hotel scope, date-range dependence, the offerRef output contract, and the refresh-before-checkout rationale. It doesn't mention pagination or limits, but that is a minor gap given 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?

Three sentences with no filler: purpose first, then workflow linkage, then when-to-call. Every sentence earns its place and the most decision-relevant information 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?

For an 8-parameter tool with no output schema, the description is reasonably complete: it tells the agent where to get the ref, what date range to use, and what to do with the returned offerRef. Minor gaps remain: the return shape is only partially described and the required hotel-identifier constraint is not made explicit.

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 reinforces the source of ref and the date range, but it adds little parameter meaning beyond what the schema already provides. It also does not explicitly clarify that a hotel identifier (ref, supplierCode, or supplierHotelId) is needed despite only checkIn/checkOut being marked required.

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 uses a specific verb ('List'), a specific resource ('bookable rooms'), and explicit scoping ('ONE hotel and date range'). It also distinguishes this tool from siblings by explaining that the returned offerRef feeds into get_checkout_quote/create_checkout.

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 clearly says to use the hotel ref from search_hotels or search and when to call: to see all of a chosen hotel's rooms or refresh availability before checkout. It names downstream tools, though it doesn't explicitly state when not to use this tool versus get_hotel_details.

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, indicating safe read-only operation. The description adds context about user scoping ('signed-in user'). However, it doesn't disclose pagination behavior or result format beyond what schema implies. With annotations covering safety, this is adequate but minimal.

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?

The description is a single, front-loaded sentence with no extraneous words. Every word is necessary to convey the purpose. Ideal conciseness for a simple 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?

The tool has no output schema and is relatively simple. The description mentions it lists hotel bookings, but doesn't specify the return format or fields. For a read-only list operation, this is minimally adequate but could be improved by noting typical response structure.

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 both parameters (page, limit). The description does not add any additional meaning beyond what the schema provides. Baseline 3 is appropriate as the schema already documents parameters clearly.

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 clearly states the tool lists the signed-in user's hotel bookings. It distinguishes from sibling tools like 'get_my_booking' (singular) and 'list_trips' (broader scope) by specifying 'hotel bookings' and 'signed-in user', though it doesn't explicitly differentiate.

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 lacks any guidance on when to use this tool versus alternatives. No explicit when-to-use, when-not-to-use, or mention of sibling tools. The agent must infer usage from the name and context.

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 annotation already marks safe read; description adds specific returned fields and the critical publicId for downstream use. No contradictions.

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 concise sentences: first describes output, second gives actionable usage hint. 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?

Despite no output schema, description fully details returned fields and links to another tool. Complete for a listing 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?

No parameters; schema coverage is 100%. Description need not add param info. Baseline of 4 justified.

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?

Description clearly states the tool lists the signed-in user's saved payment cards, specifying exact fields (brand, last 4, expiry, default). No ambiguity; distinct from sibling tools.

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 tells agent to use returned publicId with create_one_click_checkout, providing direct usage context. Does not mention when not to use, but clear purpose reduces need.

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 provide readOnlyHint=true. Description adds only 'signed-in user' context, minimal extra disclosure beyond 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?

Single short sentence, no wasted words.

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?

Minimal description for a simple read operation. Lacks detail on return format or potential limitations, but acceptable given no parameters and readOnlyHint.

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?

No parameters; baseline 4. Description adds no parameter info, which is fine.

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?

Clearly states the action (list) and resource (signed-in user's saved trips/itineraries). Distinguishes from siblings like 'list_my_bookings' and 'save_trip'.

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 explicit when-to-use or alternatives, but purpose is straightforward. Implicit that it's for viewing own saved trips.

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?

Details the cancel-and-rebook mechanism for date changes, explains special-request behavior, and introduces supplierModifyStatus. Adds significant context beyond the destructiveHint 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?

Five sentences, each providing essential information. Logically ordered: purpose, prerequisite, special-request rule, date change logic, result interpretation. No waste.

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?

Covers necessary behavioral aspects and error cases. Missing explicit output structure, but for a mutation tool without output schema, the description of supplierModifyStatus partially compensates. Could mention what happens with non-date-only changes.

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?

Adds context to verificationCode (from specific sibling), specialRequests (always apply), and date parameters (implications of change). Requires no additional clarification beyond the schema 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?

The first sentence clearly states the tool modifies a signed-in user's booking, with a specific verb and resource. It is distinct from siblings like cancel_booking or request_booking_action_code.

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 requires verificationCode from request_booking_action_code, explains when date changes fail (suppliers not supporting amendment) and advises to cancel and rebook instead. Provides post-condition guidance on supplierModifyStatus.

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?

The description adds behavioral context beyond annotations: it emails a code (non-destructive but state-changing), specifies the code is 6-digit, and explains it's a prerequisite. Annotations already indicate idempotent and non-destructive. Could mention failure scenarios, but overall good.

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 key information, no fluff. Every sentence is essential.

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 two-parameter tool with no output schema, the description covers purpose, usage, and next steps. Could mention edge cases like email failure, but information is sufficient 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds chaining context but does not elaborate on parameter semantics beyond what is in 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 clearly states that the tool emails a 6-digit verification code, required before cancelling or modifying a booking. It distinguishes itself from siblings like cancel_booking and modify_booking by positioning as Step 1 of a two-step process.

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 states that this tool is required before cancelling or modifying a booking and directs the agent to call cancel_booking or modify_booking with the code. Provides clear when-to-use and next-step instructions.

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 indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the user context ('for the signed-in user') but provides no additional behavioral details such as side effects, auth requirements, or rate limits. Adequate but not rich.

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?

The description is a single, well-structured sentence with no unnecessary words. It efficiently conveys the core purpose without fluff.

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 the complexity (6 parameters, no output schema), the description is too minimal. It omits return value hints, parameter relationships (e.g., startDate before endDate), and constraints. The agent would benefit from more context, especially with many sibling tools.

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 parameters. The description does not add any meaning beyond what the schema provides, earning the baseline score of 3.

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 clearly specifies the action ('Create'), the resource ('new saved trip (itinerary)'), and the context ('for the signed-in user'). This distinguishes it from siblings like add_trip_item (which modifies an existing trip) and list_trips (which reads trips).

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 does not provide any guidance on when to use this tool versus alternatives. It lacks explicit exclusions or mentions of sibling tools. The agent must infer from the name and sibling list that this is for trip creation only.

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 provide readOnlyHint and openWorldHint. Description adds that results can be passed to 'fetch', but lacks details on pagination, ordering, or limits. Does not contradict 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?

Two sentences front-load purpose and usage. No redundant information; 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?

Explains output type (list of IDs for fetch) but omits details on result structure, pagination, error handling, or any constraints beyond parameters. Acceptable for a search tool given rich schema but could be more complete.

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 description adds value by clarifying 'query' as natural-language and providing an example. Other parameters are well described in schema, so description moderately enhances semantics.

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?

Clearly states it searches hotels and returns IDs for use with 'fetch'. However, it does not distinguish from sibling 'search_hotels', leaving ambiguity about when to use each.

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?

Only suggests providing destination and travel dates in the query. No guidance on when to use this tool versus siblings like 'search_hotels' 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.

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

Even with `readOnlyHint: true` already present, the description adds valuable behavioral context: results are 'price-sorted', returned as 'JSON in the text', hotels carry an 'opaque `ref`', and prices are 'indicative'. It also discloses that availability is live, which informs the agent that results may be time-sensitive. 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?

The description is compact and front-loaded: purpose first, return shape second, booking flow third, and alternatives fourth. Every sentence adds operational value and none are redundant with the schema or annotations.

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 correctly takes on the burden of explaining the return value: a price-sorted list of hotels as JSON text with opaque refs and indicative prices. It also names the next steps for booking and for finding hotels not in the list. It stops short of describing pagination or result limits, but these are not essential for a correct first call.

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 adds a small amount of parameter meaning beyond the schema by explaining `keywords` as 'a hotel name, area, or amenities' and by framing `destination` plus date range as the core search scope. However, most parameter detail is already fully covered in the input 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 opens with a specific verb and resource: 'Search live hotel availability for a destination and date range.' It clearly distinguishes this tool from the generic sibling `search` and from `get_rooms`, which is positioned as a follow-up for specific hotel/room 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?

The description explicitly routes the agent through the booking workflow: call `get_rooms`, pass `offerRef` to `get_checkout_quote`, then `create_checkout`. It also gives an explicit alternative condition: 'For a hotel's other rooms (or a hotel not in the list), call `get_rooms`.' This tells the agent exactly when this tool is insufficient and what to use instead.

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