FlyBest Travel — Hotel Booking with Advisor Benefits

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses the irreversibility ('Not reversible'), the 30-minute preview validity window, the two-step consent model, the penalty-acceptance record, and the required human verification paths. No contradiction with the annotations — the repeated confirm calls are consistent with idempotentHint.

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 the two-step mechanic before the edge cases. Dense but each sentence carries a distinct rule (penalty, expired terms, missing fees, unknown result), though the penalty/fee/verification clauses could be tightened.

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?

No output schema exists, and the description compensates by explaining what a preview call returns and how the sequential flow resolves. For a destructive, stateful, non-reversible operation, the error and verification paths are all covered.

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 trip, confirm, and accept_penalty are already documented in the schema with essentially the same semantics (preview window, penalty acceptance). The description adds only light relational framing (accept_penalty records acceptance of 'the current charge'), so the baseline 3 for high schema coverage 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 one of the connected user's own bookings') and anchors the identifier to a sibling ('the number shown in my_trips'), cleanly separating it from my_trips/my_trip which only list. An agent can pick this tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes the two-call protocol (confirm=false previews, confirm=true within 30 minutes cancels) and the conditional requirement for accept_penalty when terms carry a penalty or are non-refundable. It also prescribes what to do in failure modes: changed/expired terms return a fresh preview, missing fee information needs advisor verification, and an unknown result needs booking-status verification before retry.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only the scoping fact that the booking must belong to the connected user, which is modest added value; nothing is said about errors for unknown numbers or what the returned detail contains.

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 sentence with the resource and the lookup key front-loaded. Nothing is padded or repeated.

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 a full annotation safety profile this is nearly adequate, but with no output schema the description never indicates what details the booking detail object contains or how a missing/invalid trip number is surfaced, leaving a small but real gap.

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 a single parameter with 100% schema description coverage, and the schema already states 'number from my_trips'. The description merely restates that same origin, adding no format, range, or validity detail beyond the schema, 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 names a specific resource (one of the connected user's own bookings) and the retrieval key (the number shown in my_trips), which cleanly separates it from the list-style sibling my_trips. It is clear, though the singular-vs-list distinction from my_trips is only implied rather than stated.

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 phrase 'by the number shown in my_trips' implies the agent must call my_trips first to obtain a valid trip number, which is useful workflow context. However, there is no explicit when-to-use statement, no exclusion of cancel_my_trip or the hotel/currency siblings, and no note about what happens with an invalid number.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the result is scoped to the connected user only and each entry carries an identifier. It does not mention pagination or ordering, keeping it out of 5 territory.

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 short sentences, front-loaded with the scope constraint and followed by the only other fact an agent needs (the identifying number). 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?

With no parameters, no output schema and a trivial read operation, the description covers what the tool returns and how its results feed sibling tools. Only the return ordering/pagination is unaddressed, a minor gap for a zero-arg list 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing filter syntax that does not exist.

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 the specific resource (bookings) and a key scope qualifier ('only the connected user's own'), which meaningfully distinguishes it from the other lookup siblings. It never uses an explicit verb like 'list', leaning on the title to supply that, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It routes the agent forward by explaining that each booking's printed number 'identifies it for my_trip and cancel_my_trip', effectively telling the agent this is the source of the IDs the other two tools need. There is no explicit when/when-not phrasing, so it stops at clear context rather than full routing guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavior: which rate is applied (banker's selling rate), that results are estimates only, and that on_date selects a historical rate. It stops short of describing rounding, precision, or error 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?

Three short sentences, front-loaded with the core action and rate type, then the estimate caveat, then the date parameter. No filler or repetition.

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 5-param, no-output-schema read tool, the description covers the essential agent-facing facts: what conversion rate is used, that output is an estimate, and how historical dates work. Missing only minor details like output precision or failure modes for invalid currency codes.

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 five parameters are already documented with format and examples. The description reinforces on_date semantics (DDMMMYY, past day's rate) but adds little beyond what the schema states, including the 400-day limit. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (converts) and resource (amount between currencies) and pins down the exact rate used ('banker's selling rate'). Siblings are hotel/trip tools, so no direct sibling confusion exists, but the description does not need to differentiate against an alternative converter.

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 a clear usage caveat: 'For estimates only: hotel bookings are made in the rate's own currency', which tells the agent not to treat the result as a bookable amount. It also explains when on_date matters. It does not name alternatives or exclusions, but none are obviously relevant here.

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?

Despite annotations already flagging destructive/openWorld/non-idempotent, the description discloses far more: the page's ~10-minute lifetime, that nothing is booked or charged until the guest submits and the hotel confirms, that card details never pass through this tool, that up to three pages are kept per connection and the oldest inactive one is closed, and that closing invalidates the prior link but never a page with payment in progress. It also states guest/stay details are transmitted to external booking and reservation systems, which is the key side effect for a write 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?

The purpose is front-loaded, but the body is a single undifferentiated wall of text that re-states the same guarantees repeatedly ('nothing is booked or charged', 'nothing is booked until the guest submits and the hotel confirms', 'Nothing is booked or charged by closing a page'). Several sentences do not earn their place, and the absence of paragraphing or grouping makes it slow to scan for the one branch an agent actually needs.

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 23-parameter mutation tool with no output schema, the description covers the full lifecycle: prerequisites (rate_key must match party size), refusal conditions, consent/re-display flow for changed totals, multi-room and add_to_pnr bridging, quota behaviour, and where the result surfaces (my_trips). Nothing an agent needs to invoke it safely appears to be 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 78%, so the baseline is 3, and the description largely restates parameter meaning already present in the schema (loyalty_id, expected_total, family_mode, add_to_pnr). It adds one genuinely new behavioural detail — that a missing e-mail causes the connection's own signup address to be pre-filled and confirmed on the page — but that directly conflicts with the schema's own note that email is 'required', creating ambiguity rather than resolving it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and artifact: 'Creates a one-time payment page for one rate.' It positions the tool against siblings by naming sabre_hotel_rates_coded as the source of rate_key, rooms, adults and totals, and by stating the eventual booking appears in my_trips. An agent can distinguish this from the search/rates/content tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use conditions for the non-obvious branches: family_mode=direct is the default and books actual occupancy, adult_pending only applies after the traveller explicitly chooses adults first, and 'No automatic switch to adults only takes place.' It also routes quota/limit cases ('asking again for the same stay returns the page already open') and escalates missing family occupancy to a named contact with a required data list.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuine value beyond that by scoping the payload (content only, no prices) and pointing to the rates tool, though it says nothing about auth requirements, rate limits, or failure modes for invalid hotel codes.

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, no filler. The content inventory is front-loaded and the pricing exclusion/routing follows immediately, so the agent gets the scope and the boundary in one pass.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values, and it lists the returned fields explicitly. Combined with 100% schema coverage and annotations covering safety, an agent has everything needed to invoke this 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 parameters (hotel_code, image_size) are already documented in the schema. The description mentions a photo gallery by category, which loosely relates to image_size, but adds no format or constraint detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and enumerates exactly what is returned (address, description, amenities, check-in/out times, room count, photo gallery). It also names the sibling it is not (rates come from sabre_hotel_rates_coded), so an agent can distinguish it from sabre_hotel_rates_coded without opening either 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?

The second sentence explicitly routes pricing lookups to sabre_hotel_rates_coded, and the schema notes the hotel_code comes from sabre_hotel_search, implying the correct call ordering. It stops short of an explicit when-to-use statement or exclusions for the other siblings, but the alternative is named clearly.

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

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

Annotations already establish readOnlyHint=true and idempotentHint=true, so safety is covered. The description goes further by disclosing important behavioral traits: calls without hotel_name or chain_code are refused before sending, loyalty_id carries into bookings, members-only rows are restricted, and family_quote_token must travel unchanged. It also documents output structure (rate fields, benefits, cancellation terms) beyond what annotations provide, though it doesn't mention rate limits or 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?

The description is extremely dense and runs over 300 words in a single paragraph, with no headings or front-loaded summary. While the opening sentence is reasonably direct, critical usage guidance is buried mid-paragraph, making it hard to parse quickly. Many sentences contain multiple clauses and parentheticals that could be streamlined or moved to the 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 19 parameters, no output schema, and high schema coverage, the description attempts to cover a lot but does so unevenly. It explains important edge cases (family quotes, loyalty programs, room arrangements) but omits how results are structured, what 'truncated' means in practice, or how to interpret occupancy.children_honoured beyond the schema. The escalation path to Jay is stated, which is useful, but the overall completeness is adequate rather than thorough.

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 95%, so the schema already documents nearly all parameters. The description adds contextual meaning: it explains that hotel_name and chain_code select partner rates, that loyalty_id is sent to the hotel and carries into bookings, and that rooms=2 prices two rooms with a combined rate_key. Some parameter mentions (e.g., currency, with_perks) repeat what the schema already says, but the added behavioral context is valuable.

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's opening states it returns 'the authoritative rate list for one hotel through the agency's reservation access,' which identifies the resource, but it's immediately buried in a dense enumeration of return fields and behavioral details. The description does not differentiate itself from sabre_hotel_search or explain why an agent would use this tool over sibling hotel tools, leaving the core purpose less clear than it should be.

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 implicitly covers some tricky edge cases (family vs adults-only searches, separate quotes for different room arrangements, when to escalate to Jay), but it never states when an agent should choose this tool over sabre_hotel_search or sabre_hotel_content. The guidance is embedded in operational detail rather than presented as clear usage conditions.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context on top: the sample-date defaults when check_in/check_out are omitted, the first-line date disclosure, the provisional-pricing caveat, the latitude/longitude refusal rule, the membership question trigger, and the confirmation-to-payment-page flow.

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 and scoping are front-loaded, but the text is a long run-on that blends input semantics, return-value detail, and conversational UI narrative (membership question position, booking reminder, payment page). Some of that narrative adds little for tool selection and dilutes the core guidance.

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 9 parameters and no output schema, the description must carry the return-value burden, and it does: it lists the fields returned, the sample-date first line, and the closing notes. It is close to complete, with only minor ambiguity about pagination or result limits.

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 78%, so most parameters are self-documented, but the description adds real meaning: the concrete sample-date defaults (about 30 days ahead, 2 nights, 2 adults unless adults is given) and the behavioural coupling of check_in/check_out are not spelled out in the schema. This meaningfully goes beyond the field 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?

States a concrete verb+resource (search hotels near a place) and enumerates the returned fields (names, Sabre codes, star rating, distance, provisional lowest rate, partner flags). It explicitly routes bookable rates to sabre_hotel_rates_coded, so the agent can distinguish it from that sibling 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?

Says it answers questions about hotels, where to stay, hotel prices and availability, and names the alternative (sabre_hotel_rates_coded) for bookable rates and terms. That is a clear use condition and an explicit alternative, but it never states when not to use this tool versus sabre_hotel_content or the other siblings.

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