Gondola Award Travel Search

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

Annotations already indicate destructive=true and readOnly=false, which cover the side-effect profile. The description adds a few generic behavioral facts ('requires guest details...') but does not disclose additional consequences like charges, confirmation handling, or rate-specific guarantees. It is not contradicted by annotations, and the existing annotations lower the bar for this dimension.

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: three lines that state purpose, prerequisite flow, and dependency sourcing. No filler or redundancy, and the key action is front-loaded 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?

With 9 parameters, an output schema, and annotations, the description covers the essential flow: linking get_hotel_rates and get_payment_methods. Optional parameters such as travel_profile_id and loyalty_account_id are documented in the schema, so the description does not need to repeat them. It is sufficient for an internal-flight booking action in this codebase.

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 descriptions cover 100% of parameters with strong contextual info (e.g. doc location from get_payment_methods). The description repeats that gondola_rate_id comes from get_hotel_rates and payment_id from get_payment_methods, which essentially restates the schema. It adds no new meaning beyond what the schema already provides, so the baseline of 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?

Directly says 'Book a hotel room', a specific verb and resource, and explicitly ties it to get_hotel_rates. This clearly distinguishes it from sibling book_vehicle and other tool names in the same group.

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?

Provides clear context for using the tool: it requires a rate from get_hotel_rates, guest details, and a saved payment method found via get_payment_methods. It does not explicitly mention when to avoid it or contrast with book_vehicle, but the prerequisite flow is well specified.

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 a mutating, destructive operation, so the description does not need to restate that. It adds useful context about required prerequisites and where parameters originate, but it does not disclose side effects like charges or confirmation behavior, which would strengthen transparency.

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 immediately followed by the most critical prerequisites. Every sentence adds useful information with no 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 output schema, full parameter descriptions, and annotations, the description is sufficient for correct invocation. It covers prerequisites and parameter provenance; only minor extras like confirmation or charge behavior are left out.

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 already describes all parameters with 100% coverage, so the baseline is 3. The description adds cross-reference value by explaining that vendor_code, rate_code, acriss_code, and search_id all come from search_vehicles results, and that payment_id comes from get_payment_methods.

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: 'Book a rental vehicle from a search result.' It clearly differentiates from sibling tools like book_hotel and cancel_vehicle_booking by focusing on rental vehicles and the booking action.

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: a Gondola account and a saved payment method, and points to get_payment_methods for finding the payment ID. It also tells the agent that key identifiers come from search_vehicles results, which is strong usage guidance, though it does not mention when to avoid this tool.

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 disclose the destructive and non-read-only nature (destructiveHint=true, readOnlyHint=false), so the description does not need to repeat that. It adds no deeper behavioral context such as irreversibility, refund implications, or cancellation-policy effects, and the confirm parameter's reference to a 'preview call' is the only related signal.

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 clean sentences, front-loading the primary action and identifier in the first clause. Every sentence contributes—the first defines the operation, the second defines the intended context.

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 core use case is covered, and an output schema exists so return-value details are unnecessary. However, the description omits the material workflow that the confirm parameter relies on, namely that the user must see the cancellation terms from the preview call before cancellation is executed. Leaving this only to a parameter description makes the top-level guidance incomplete for a safe 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%, and booking_id and confirm already are well-documented in the input schema. The description only restates that the booking is identified by a Gondola booking ID, adding minimal new parameter nuance.

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 ('Cancel'), a specific resource ('existing vehicle booking'), and the exact identifier ('Gondola booking ID'). It clearly distinguishes this tool from the sibling suite, where no other tool has a cancel-vehicle purpose.

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 an explicit trigger: 'Use this when a user wants to cancel a rental they previously booked.' It does not mention alternatives or when-not-to-use conditions, though the uniqueness of the purpose makes exclusions less critical.

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 signal readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail beyond that: it renders a rate_comparison widget and returns specific valuations (cash rate, points rate, CPP, deal scores). This gives the agent a clear picture of what invoking the tool will do and what it will produce.

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 front-loaded with the core purpose, then gives usage context, parameter guidance, and return values in four focused sentences. Every sentence earns its place, and the examples are compact yet illustrative.

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 purpose, when to use, how to source hotel_ids, the valid array size, required dates, and outputs. With full schema coverage and an output schema present, nothing essential is missing for an agent to select and invoke this tool 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 the baseline is 3. The description's parameter guidance—'Pass an array of one to five hotel_ids resolved from search_hotels'—mostly repeats what the schema already states. It adds no new semantic detail beyond the schema, so no higher score is warranted.

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 clear verb-resource pair: 'Compare cash vs points rates' and mentions rendering a side-by-side rate_comparison widget. It also names the specific outputs (cash rate, points rate, CPP valuation, deal scores), which clearly distinguishes it from sibling tools like get_multi_night_rates or diagnose_rates.

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 states when to use the tool: 'Use this whenever the user is making a cash-vs-points decision.' It gives concrete example phrasings and covers both single-hotel and multi-hotel scenarios. It does not explicitly list when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with a mutation that is not destructive. The description adds behavioral detail: the user is notified by email when the rate drops, and the optional date logic. It does not contradict annotations and provides useful side-effect information beyond the structured fields.

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-loaded with the core purpose, and contains no filler. It efficiently covers the purpose, notification, and optional parameter 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?

Given a simple 3-parameter tool with an output schema and annotations covering safety, the description is sufficiently complete. It states the purpose, optionality, and side effect. No critical missing information for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters are documented. The description adds value by explaining that omitting checkin/checkout monitors any two-night stay, which clarifies the optional usage beyond the schema's basic 'optional' designation. It does not repeat schema descriptions but supplements them with behavioral 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?

The description clearly states the tool creates a rate alert for a hotel to monitor price drops, and explicitly notes the email notification. It uses a specific verb (create) and resource (rate alert), and is distinguishable from sibling tools like delete_rate_alert and get_rate_alerts.

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 clear context for when to use the tool: to monitor a hotel for price drops. It also explains the optionality of dates, noting that leaving them out monitors any two-night stay. However, it does not explicitly mention alternatives or exclusions, though the sibling list makes the purpose quite clear.

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 destructiveHint=false. The description adds behavioral context beyond that by explaining the result's interpretive value ('tells the user whether they can decline the rental company's expensive insurance') and confirming this is a non-mutating lookup. 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?

Three sentences with no filler. Purpose is front-loaded, the use case is explained in a compact aside, and the parameter guidance is condensed into one clear either/or sentence. 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?

Covers purpose, timing, parameter alternatives, and result interpretation, and the output schema covers return structure so it need not be repeated. Minor gap: it doesn't explicitly distinguish itself from the sibling get_vehicle_booking_coverage tool, though the credit-card framing makes confusion unlikely.

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 already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: it specifies the exclusive either/or relationship between credit_card_product_name and card_number_bin + card_provider, and explains that the BIN path is network-tier-based while the product name path is exact-match.

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 lookup operation ('Look up rental car CDW/LDW coverage'), names the exact resource (credit card coverage), and ties it to a concrete decision (declining rental company insurance). It is clearly differentiated from sibling booking-coverage tools by focusing on credit-card-provided coverage rather than booking-level coverage.

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 frames when the tool is useful ('before booking') and gives clear either/or parameter guidance for invocation. However, it does not explicitly name alternatives or exclusion conditions, such as when get_vehicle_booking_coverage would be more appropriate.

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 indicate destructiveHint=true and readOnlyHint=false, which align with the description. The description adds functional context beyond the annotations by explaining that deleting an alert stops price-drop monitoring.

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?

One concise sentence with no filler. The action, object, and purpose are front-loaded and immediately understandable.

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 single-parameter destructive tool with a documented parameter and output schema, the description fully covers what an agent needs to understand the operation and its intended use.

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 the single alert_id parameter clearly described as 'The rate alert ID to delete'. The description itself adds no additional parameter meaning, so the baseline score 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 uses a clear verb ('Delete') and resource ('rate alert'), and immediately explains the purpose ('to stop monitoring a hotel for price drops'). It is unambiguous and distinct from other 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?

The phrase 'to stop monitoring a hotel for price drops' provides clear context for when this tool should be used. It does not explicitly name alternatives or exclusions, but no obvious alternative exists among siblings.

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 destructiveHint=false, so the safety profile is covered. The description adds the context that it returns per-source status and a full rate breakdown, and that it is diagnostic, which is useful but not essential given the output schema carries return details.

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, each earning its place: a precise function statement, concrete use-case triggers, and an exclusionary closing note. There is no filler or repetition of schema content.

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 a high-coverage schema and an output schema present, the description provides enough additional context: when to call it, example questions, and the distinction from casual recommendations. Nothing critical is missing for an agent to select and invoke this tool 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 coverage is 100%, so every parameter is already documented in the input schema. The description reinforces the notion of per-supplier statuses but does not add meaning beyond what the schema provides, which matches 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 opens with a specific verb and resource — 'Diagnose rate availability and per-supplier statuses for a specific hotel' — and grounds it in concrete user questions like 'why is there no AAA rate?'. It clearly distinguishes itself from sibling tools by stating it is diagnostic and not for casual recommendations.

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 provides an explicit when-to-use trigger: when a power user asks why certain rates aren't showing, with two concrete examples. It also excludes casual recommendation use, but it does not name specific alternative tools to use instead, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint true and destructiveHint false; the description adds important behavior beyond that: alternate confirmation numbers will not resolve, and imported email reservations lack IDs. This prevents failed calls and instructs fallback behavior, giving the agent a clear model of what the tool can and cannot do.

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 four sentences but each sentence earns its place: what it does, what it returns, what it won't resolve, and when to use an alternative. It is front-loaded with the core purpose and contains 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 single-parameter read-only tool with an output schema, the description covers the full decision space: source of the ID, expected output, failure conditions, and fallback tool. An agent has everything needed to decide whether to call this tool and how to pass the parameter.

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 already documents booking_id at 100% coverage, so the baseline is 3. The description adds practical meaning by naming the exact display label 'Gondola booking', excluding hotel/airline confirmation numbers, and clarifying that email-imported reservations have no booking ID. These constraints go beyond the bare schema text.

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: 'Get details for a hotel booking made through Gondola.' It enumerates the returned fields (hotel name, dates, room type, rate, status, cancellation policy) and clearly scopes the tool to Gondola bookings, distinguishing it from sibling tools like get_booking_link and get_vehicle_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?

It explicitly tells the agent when to use it: with the Gondola booking ID shown by get_upcoming_trips and get_past_trips. It also gives strong when-not-to-use guidance: confirmation numbers will not resolve, and email-imported reservations have no Gondola booking ID, so the agent should answer from get_upcoming_trips/get_past_trips instead.

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 destructiveHint=false, so the safety profile is covered. The description adds behavioral detail beyond annotations: it returns a URL, pre-fills dates, and changes link destination when gondola_rate_id is present. No contradiction with annotations is present.

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 main purpose, followed by usage context and optional-parameter behavior. Every sentence contributes meaningful guidance, with no repetition of schema details or 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?

The description covers purpose, when to use it, what it returns, and how the optional parameter changes behavior. With an output schema present and annotations covering the read-only nature, the description is complete for an agent to select and invoke this tool 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 coverage is 100%, so parameters are already well-documented in the schema. The description adds value by clarifying the effect of gondola_rate_id (deep-linking to that rate's checkout page) and the pre-filled dates behavior, which enriches the schema's basic parameter 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 description clearly states a specific verb ('Get'), a resource ('a booking link for a hotel on Gondola'), and the core behavior (returns a URL with dates pre-filled). It distinguishes itself from sibling tools like book_hotel and get_vehicle_booking_link by specifying 'hotel' and the return of a URL rather than performing a 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?

It explicitly says 'Use this when a user wants to book a specific hotel,' giving a clear context. It also provides conditional guidance for the optional gondola_rate_id to deep-link to a rate's checkout page. However, it does not explicitly contrast itself with book_hotel or other booking-related siblings, so some inference is left 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?

Annotations already mark it read-only and non-destructive, so the description only needs to add extra context. It discloses that only active credits are returned, that credit/confirmation numbers are deliberately hidden, and that expiration dates are included 'when known'—useful behavioral nuances beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: what the tool returns, the return fields, when to use it, and a key limitation. Information is front-loaded and there is no 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?

For a zero-parameter read-only tool with an output schema, the description covers purpose, return content, invocation triggers, and privacy limitations. Nothing an agent needs to call it correctly appears 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?

The tool has zero parameters and schema coverage is trivially 100%, so the baseline for parameter semantics is 4. The description correctly focuses on behavior and return data rather than parameters, needing no additional compensating detail.

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 ('airline flight credits, eCredits, travel funds, vouchers, and travel-bank balances') with a clear verb ('Get'), and lists the returned fields. It implicitly distinguishes itself from the sibling get_free_night_credits by focusing on airline/travel credits rather than hotel free-night credits.

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 guidance: 'Use this whenever the user asks whether they have unused airline money, credits from cancelled flights, or travel vouchers.' This is a clear invocation condition, though it does not mention when not to use it or name an alternative tool.

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 readOnly/openWorld annotations, the description adds important behavioral details: it reveals per-program result structure, distinguishes cash itineraries paired with award pricing from award-only itineraries, and defines the timeout vs no_results response states. It clarifies what the open-world nature means in practice for polling.

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 yet complete, with a clear opening purpose, explicit call sequencing, return summary, and edge-case semantics. Every sentence contributes unique, operationally useful information without 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 polling tool with an output schema, the description covers the necessary context: prerequisites, parameter intent, expected response contents, and how to interpret ambiguous statuses. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the consequence of omitting pending_sources (polling every program, including those never searched), which goes beyond the schema's parameter description. Other parameters are adequately covered by the schema and the description's 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?

The description uses a specific verb ('Collect award pricing') and resource ('a flight search'), and clearly distinguishes this from other sibling tools by tying it to search_flights responses with pending_sources. It avoids the tautology of the tool name and explains the exact domain.

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 explicitly states when to call this tool: after search_flights with points:true and a pending_sources response. It also explains why pending_sources matters, but it does not explicitly mention alternatives or when-not-to-use scenarios, leaving room for a higher score.

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 a safe read-only operation, and the description adds meaningful behavioral context: certificates expire unused, near-expiration should be surfaced proactively, and coverage for a specific hotel must not be inferred from the cap. This goes well beyond the structured annotations without contradicting them.

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 longer than average, but every sentence earns its place: it defines the resource, lists return contents, gives routing guidance, warns about expiration behavior, and sets a boundary on inference. Key guidance is front-loaded before the alternative-tool mention.

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 zero parameters and an output schema available, the description has very little it must cover, yet it still provides the critical distinction from get_loyalty_accounts, expiration-handling guidance, and a limitation warning. The tool is fully specified for an agent to select and invoke 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?

The input schema has zero parameters, so there is no parameter burden to clarify. The description nonetheless clarifies what the tool does not need and emphasizes the conceptual distinction from points balances, which is useful for the agent.

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 ('free night certificates') and explains exactly what those are with concrete examples across loyalty programs. It also distinguishes them from points balances, which prevents confusion with a sibling tool.

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 explicitly says 'use this rather than get_loyalty_accounts whenever the user asks about certificates, free nights, or award nights' and provides example queries. It also states a clear non-use: the tool does not evaluate property-level certificate coverage.

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 readOnlyHint=true and destructiveHint=false, but the description adds important behavioral context: 'Content only, with no dates or availability' and the '+N more' truncation for long lists. This warns the agent about data incompleteness, which is valuable beyond annotations. 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 long but front-loaded with the core purpose and includes a detailed list of content. Every sentence serves a purpose, and the critical usage guidance appears at the end without cluttering the main message. It is comprehensive without being redundant.

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 an output schema, so return structure is covered. The description covers the input source, the scope (content vs. availability), the truncation behavior, and the sibling distinction. For a single-parameter read-only tool, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes hotel_id as 'The hotel's Vervotech property ID (returned by search_hotels).' The description adds no new semantics beyond that, so it relies on the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('stored property information for a specific hotel') and enumerates the exact attributes returned. It also distinguishes itself from siblings by naming search_hotels as its precursor and get_hotel_rates for prices, making its scope unambiguous.

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 when to use ('after search_hotels when the traveler wants to learn more about a property') and when not to ('use get_hotel_rates for prices'), plus clarifies it is content-only with no dates/availability. This gives clear 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?

Beyond the readOnlyHint annotation, the description discloses that 'rates may say they are still loading; call again in a few seconds before concluding... unavailable,' explaining the retry behavior. It also reveals that only bookable rates (direct/GDS) are shown and that other variants are collapsed, providing important context for interpreting results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is multi-sentence but well-organized: it opens with purpose, then groups rates, explains limitations, retry caveat, and usage context. Each sentence adds necessary detail without redundancy, making it appropriately sized for the tool's complexity.

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 essential operational details: rate grouping, rate_id for booking, filtering of supplier-only rates, loading behavior, and past-date handling. With an output schema present, it does not need to describe return values, so this is complete for an agent to invoke 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?

The input schema already provides full descriptions for all four parameters (100% coverage), so the description does not need to add much. It does add context by implying hotel_id comes from search_hotels and referring to the 'stay window' for dates, but this is marginal beyond the schema.

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

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

The description starts with 'Get live room rates for one hotel and stay window,' which is a specific verb-resource-scope statement. It clearly differentiates from siblings like get_multi_night_rates (by 'one hotel and stay window') and search_hotels (by being the follow-up step for availability).

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 explicitly states 'Use this after search_hotels when the traveler wants availability or booking options,' giving clear timing and intent. It also notes the 'past stay dates return a notice' limitation, but does not explicitly name alternatives like get_multi_night_rates or compare_rates for other use cases.

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 destructiveHint=false, so the description correctly aligns with them. It adds beyond the annotations by disclosing the return limit ('up to 10 recent reviews') and the content type ('ratings and comments'), giving useful behavioral context without contradicting 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?

The description is two tight sentences. The core purpose is front-loaded, the use case is clearly stated, and the return limitation is included without any filler or repetition of schema details.

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 a single well-described parameter, an output schema present, and annotations covering the read-only and non-destructive nature, the description fully covers what an agent needs to select and invoke this tool correctly. There are no significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the single parameter hotel_id with 100% coverage, including its type and origin from search_hotels results. The description does not add much parameter-level meaning beyond tying the tool to a specific hotel, so the baseline 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 action ('Get guest reviews') and a clear resource ('for a specific hotel'), and differentiates itself from sibling tools like get_hotel_details and get_hotel_stats by emphasizing guest feedback. It also specifies what is returned, making the tool's role unmistakable.

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

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

The description provides clear usage context: use this when helping a user understand guest opinions, common complaints, recurring praise, and recent service issues. It does not explicitly mention when not to use it or name alternative sibling tools, but the use case is concrete enough to guide an agent effectively.

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 destructiveHint=false, so safety is covered. The description adds useful context about historical observations and percentile interpretation, but does not disclose potential limitations such as insufficient data or behavior when no history is available.

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, no filler, with the core function front-loaded and a helpful clarifying example. 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?

The description, combined with the full parameter schema and output schema, gives an agent enough to call the tool correctly. It clearly states purpose and output semantics, though it could briefly mention the optional nightly_points_cost behavior or data availability caveats.

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 fully documents all parameters. The description does not add explicit parameter-level meaning beyond referring to the 'current rate,' which maps to nightly_cash_cost. Baseline 3 applies because the schema handles 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 specifies the verb 'Get' and the unique resource 'pricing percentile context for a specific hotel.' It immediately distinguishes this tool from siblings like predict_price, compare_rates, and diagnose_rates by focusing on percentile context relative to historical property pricing.

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 a clear usage context: 'Use this to add objective context to recommendations.' It does not explicitly mention alternatives or when not to use it, but the intended scenario is stated well enough for an agent to decide.

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 destructiveHint=false, so the safe-read nature is known. The description adds valuable behavioral context: it returns only points balances and elite tiers, explicitly excludes free night certificates, and states where those are tracked. This goes beyond what annotations provide.

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, with the core action and resource front-loaded. The second sentence earns its place by disambiguating from a sibling and preventing an incorrect call. 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?

Given the tool has no parameters and an output schema exists, the description fully covers the essential information: purpose, scope, exclusions, and sibling routing. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline of 4 applies. The description correctly focuses on what the tool returns rather than parameters, and the empty schema requires no additional clarification.

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 ('Get'), a specific resource ('the user's loyalty program memberships and current point balances'), and clearly distinguishes it from the sibling tool get_free_night_credits by explicitly saying free night certificates are NOT returned here. An agent can immediately tell what this tool does and what it does not cover.

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 concrete use cases: personalizing recommendations and suggesting portfolio optimizations. It also explicitly excludes free night certificates and directs the agent to the alternative tool get_free_night_credits, making the decision boundary unambiguous.

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 mark the tool as read-only and non-destructive, and the description adds useful behavioral detail: it returns per-checkin-date nightly rates and supports day-of-week pattern discovery. Nothing in the description contradicts 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 front-load the core behavior, then give the usage trigger, then explain the value of the returned data. The third sentence slightly overlaps with the first, but it earns its place by clarifying why the calendar-style output matters.

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, combined with 100% schema parameter coverage and an output schema, gives an agent everything needed to select and call this read-only tool correctly. No critical guidance about return behavior or prerequisites is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 and the description need not repeat parameter docs. It adds only a light semantic gloss about date range and per-checkin-date output, without enriching the meaning of the `nights` parameter beyond the schema.

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

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

The description clearly states the operation: fetching a rate calendar for a hotel over a date range, with the purpose of recommending cheapest nights. It implies a distinction from siblings through the flexible-dates use case, but it does not explicitly name or rule out alternative 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?

It gives an explicit trigger: use when a user has flexible dates such as 'any week in May.' It does not list exclusions or alternatives, but the intended context is clear and actionable.

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 destructiveHint=false. The description goes well beyond these by detailing the return structure (fields like dates, confirmation numbers, seat assignments), the Patterns block summarising whole history, pagination behavior, and the caveat that seat data depends on Gondola parsing. It also provides guidance on reading the Patterns block for seat-related questions. 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 long (multiple sentences) but every sentence adds unique value: purpose, examples, return fields, patterns block, usage guidance, pagination. It is slightly verbose but well-structured, front-loading the purpose and use case before details. No 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 tool's complexity—many returned fields, a Patterns block summary, pagination, and a caveat—the description covers all necessary aspects. It explains what the tool returns, how to access more data (page), how to interpret the Patterns block, and warns against premature claims of missing seat data. The presence of an output schema further reduces the need to describe return structure, so this is 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 both page and limit are already fully documented. The description's note about passing page=2,3 to walk back mirrors the schema's description. It adds no new parameter semantics beyond the schema, so the baseline score of 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 opens with a clear, specific statement: "Get the user's past hotel stays and flights," identifying both the resource (travel history) and the operation (retrieval). It then reinforces purpose with concrete examples of supported questions (seat preferences, airline loyalty). This distinguishes it from siblings like get_upcoming_trips by explicitly saying 'past'.

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 states when to use it: for travel-history questions and behavioral recommendations, with multiple examples. It also gives a strong directive: "do not say seat data is unavailable until this tool has been checked," preventing premature errors. However, it does not name the specific sibling alternatives (e.g., get_upcoming_trips) or state when not to use it, 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?

Annotations already mark the operation as read-only and non-destructive. The description adds meaningful context about what is returned (credit/debit cards and payment IDs) and why, which is useful for the agent.

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 with no filler. The main action and key return value are front-loaded, and the booking context is included efficiently.

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 zero parameters, an output schema present, and safe read-only annotations, the description sufficiently explains what the tool does and why it is used. Nothing essential is missing 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?

The tool accepts no parameters and the schema has no properties, so there is little for the description to add. The baseline of 4 applies because parameter semantics are effectively irrelevant here.

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') and resource ('user's saved payment methods'), and clarifies the purpose: returning credit/debit cards with payment IDs for booking. It clearly distinguishes itself from the many other get_* sibling tools by connecting to the book_hotel tool.

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 clear context: this is for booking and provides inputs needed for book_hotel. It doesn't explicitly exclude alternatives or state when not to use it, but the intended use case is evident.

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 destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying the scope ('active', 'current user') and the return semantics ('which hotels the user is monitoring for price drops'). No contradiction exists.

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 short sentences with no filler. The first sentence front-loads the action and scope, and the second adds valuable output detail. Every word contributes to understanding.

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

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

For a zero-parameter, read-only tool with an output schema and safe annotations, the description is complete. It states the resource, user scope, active-filter semantics, and the nature of the returned data, leaving no operational gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so there is nothing to document at the parameter level. The baseline of 4 applies, and the description appropriately clarifies what the tool returns rather than inventing parameter details.

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 action and resource: 'Get all active rate alerts for the current user.' It further clarifies the output as which hotels the user is monitoring for price drops, making it easy to distinguish from rate comparison or prediction siblings like compare_rates and predict_price.

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 clear context: this tool is for retrieving the current user's active rate alerts, so an agent knows when to invoke it. It does not explicitly name alternatives or exclusions, but no sibling tool appears to serve this exact purpose, so the 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 declare readOnlyHint=true and destructiveHint=false. The description adds value beyond these by explaining that results are 'matched by hotel attributes and amenities' and that current rates are returned. This gives the agent a realistic expectation of output without contradicting 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 zero filler. The core purpose is front-loaded, the usage scenario and destination nuance are covered, and the return content is stated. 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?

With an output schema present, annotations covering the read-only safety profile, and 100% parameter schema coverage, the description completes the picture by explaining the tool's niche, the destination override, and the type of results returned. Nothing essential for calling this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the destination parameter ('when the alternatives should be in a different city') that goes beyond the schema's generic 'Optional destination city or place.' It also implies the hotel_id is the seed for similarity matching.

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 opens with a clear verb and resource: 'Find hotels similar to a given hotel.' It further distinguishes the tool from initial search by framing it as 'branching exploration after a search' with a concrete example, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('branching exploration after a search') and explains when to pass destination ('when the alternatives should be in a different city'). It does not explicitly name alternative tools or state when not to use it, 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 mark this as read-only and non-destructive. The description adds meaningful behavioral context by explaining that results are personalized based on preferences, recent searches, popular destinations, and upcoming holidays, which goes beyond the annotation metadata.

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 concise, with three purposeful sentences: what it does, what it returns and why, and when to use it. Every sentence adds value and the usage examples are front-loaded after the main purpose.

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, zero parameters, read-only annotations, and an existing output schema, the description is fully sufficient. It explains the personalization basis and gives usage context, leaving no critical gaps for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema coverage is 100%, so there is no parameter documentation burden. The description appropriately implies that the tool uses implicit user context rather than explicit inputs.

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's function: getting personalized travel suggestions and trip inspiration for the current user. It also specifies the resource (curated hotel recommendations) and distinguishes it from more transactional tools like search_hotels or get_hotel_details by emphasizing open-ended inspiration.

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 concrete example prompts such as 'where should I go?' and 'any trip ideas for next month?', making the intended use case clear. It does not explicitly name alternatives or exclusion criteria, but the 'open-ended prompts' framing implicitly distinguishes it from structured search 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 and destructiveHint=false, and the description is consistent with those. It adds value by specifying the returned scope (active awards/certificates across loyalty programs) and the output fields (program, award type, remaining count, expiration date), which goes beyond the structured 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 front-load the action and resource, then provide return fields, then usage guidance and an exclusion. Every sentence earns its place with no redundant 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?

For a zero-parameter read-only tool with an output schema, this description is complete. It covers what the tool returns, when to use it, and how it differs from adjacent award categories, which is everything an agent needs to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description has no parameter semantics to document. With no input schema details needed, the baseline of 4 applies; the description appropriately focuses on selection and output behavior instead.

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 opens with a specific verb and resource: 'Get the user's active suite upgrade awards and certificates across loyalty programs.' It also clarifies the returned fields and explicitly separates suite upgrade awards from free-night certificates and points balances, so an agent can distinguish it from sibling tools like get_free_night_credits.

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 trigger conditions: use whenever the user asks about suite upgrades, Nightly Upgrade Awards, Suite Upgrade Awards, Confirmable Upgrade Rewards, or IHG suite upgrades. It also states what the tool is not for by noting these awards are separate from free-night certificates and points balances.

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 mark readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: it aggregates stated and learned preferences and frames itself as 'the single best source of who this traveler is.' It does not contradict 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?

The description is three sentences with no filler: definition, usage instruction, and alternative tool routing. It is front-loaded with the core purpose and 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?

For a zero-parameter read-only tool with an output schema and annotations, the description fully covers what data the tool returns, when to call it, how to use its output, and how it relates to a key sibling tool. Nothing essential 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?

The tool has 0 parameters, so schema description coverage is effectively complete. No parameter explanation is needed, and the description does not introduce any misleading parameter-related information.

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 what the tool does: 'Get the user's saved travel context' and enumerates the contents (loyalty programs, home airport, preferred airlines, hotel chains, trip patterns). It also distinguishes itself from get_past_trips by noting the latter provides raw past reservation evidence, so an agent can tell them apart.

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 usage direction: call it once at the start of a travel or planning session and weigh it when recommending hotels, flights, or cars. It also names a specific alternative (get_past_trips) for raw past-reservation evidence, providing clear when-not-to-use 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?

It adds meaningful context beyond the readOnlyHint annotation by describing the returned data (name/email/phone presets) and the reusability of each profile's ID as travel_profile_id in book_hotel. This reveals the tool's role as a building block for a follow-up booking action, which annotations alone don't convey.

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 packed with information across three sentences, all of which contribute: the resource, the ID linkage, and the when-to-use guidance. It's slightly wordy (e.g., the website-checkout analogy) but not padded.

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 zero-parameter read-only tool with an output schema, this description fully equips an agent: what it returns, how the ID should be consumed by book_hotel, and when to call it. Nothing essential 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?

With zero parameters and 100% schema coverage (vacuously), the description's mention of the user's saved profiles implicitly confirms the tool operates on the current user context. There are no parameter semantics to add; the baseline of 4 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 opens with a specific verb+resource: 'Get the user's saved travel profiles' and enumerates the contents (guest name, email, phone presets). This clearly distinguishes it from sibling tools like update_traveler_profile or get_user_preferences by naming its exact subject matter.

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 explicitly recommends calling before booking and explains the downstream benefit ('book as <traveler>'), which tells the agent when to use it. It doesn't name alternatives or exclusions, but the booking-context guidance is a clear usage cue.

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 destructiveHint=false, so the safety profile is covered. The description adds value beyond that by enumerating exactly what data comes back (confirmation numbers, loyalty programs, ticket class, miles redeemed, refundability timing) and by disclosing a real limitation: seat assignments are only returned 'when Gondola has parsed real row+letter seats from airline emails.' This conditional availability caveat is genuinely useful 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?

The structure is good: purpose is front-loaded in the first sentence, followed by use cases and then return details. However, the final sentence is a long enumeration of roughly a dozen return fields (status, costs/rates, savings/AutoSave signals, ticket class, miles redeemed, etc.) that substantially overlaps with what the existing output schema already documents. The jargon phrase 'savings/AutoSave signals' adds cognitive load without clear benefit, making the description slightly bloated.

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 0-parameter, read-only fetch tool with safety annotations and an output schema, this description is complete. It covers what the tool returns, when to invoke it with concrete scenarios, whose data it accesses, and the one meaningful data-availability limitation (parsed seat assignments). Nothing an agent needs to correctly select and call this tool 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?

The tool has 0 parameters, so the baseline is 4. There are no parameter semantics to explain; the description spends its words on return-value semantics instead, which is appropriate for a parameterless fetch tool.

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 names a specific verb and resource: 'Get the user's upcoming hotel, flight, and rental car reservations.' The 'upcoming' scope cleanly distinguishes it from the sibling get_past_trips, and the return-field enumeration further clarifies what the tool covers. An agent can tell exactly what this tool does without opening the schema or any sibling.

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 concrete, grounded use cases: grounding recommendations in real plans with a realistic example ('your Tokyo trip is May 15-20'), checking confirmation numbers, and answering what trips are already booked. It does not explicitly name an alternative or state when not to use it, though the 'upcoming' scope implies the get_past_trips exclusion rather than stating 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?

Annotations already convey readOnlyHint=true and non-destructive behavior. The description adds meaningful context beyond that by specifying the returned fields and the fact that it is a retrieval of already-booked rental details, which helps set expectations about scope and output. It does not mention edge cases or error behavior, but the annotation coverage keeps the bar lower.

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: the first sentence states the action and output, the second sentence gives concrete usage guidance. No filler or redundant restating of the tool name or 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?

This is a low-complexity read-only tool with one parameter, a fully documented schema, and an output schema present. The description covers purpose, output fields, and when to use it, so nothing critical is missing for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter booking_id is already fully documented in the input schema, including what it is and what it is not (a vendor confirmation number), with 100% schema description coverage. The tool description does not add additional parameter semantics, so the 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 uses a specific verb ('Get details') with a clear resource ('a specific vehicle booking by its Gondola booking ID') and enumerates the returned information (vendor, pickup/dropoff locations and times, vehicle class, rate, status). This clearly distinguishes it from generic get_booking and vehicle-specific siblings like get_vehicle_booking_link and get_vehicle_booking_coverage.

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 when to use the tool ('Use when a user asks about a rental they've already booked') and gives concrete example user queries. It does not explicitly state when not to use it or name exclusion conditions versus sibling tools, so it falls just short of a 5.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by noting the coverage is 'stored at booking time,' implying it is a historical snapshot rather than live card coverage. It does not discuss auth or rate limits, but those are less important for a low-risk read operation with an output schema.

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 first sentence states the operation, and the second provides actionable usage context. Every phrase 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?

The description is complete for the tool's complexity: one required parameter is documented, the operation is read-only per annotations, an output schema exists, and the description supplies both data-freshness context and a clear use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the only parameter booking_id already has a clear description ('The Gondola booking ID of the vehicle booking'). The tool description adds little beyond the schema, so baseline 3 is appropriate.

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

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

The description names a specific verb ('Get'), a specific resource ('rental car CDW/LDW coverage'), and a specific scope ('stored at booking time for a specific vehicle booking'). This distinguishes it clearly from sibling tools like get_vehicle_booking or credit_card_coverage.

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 concrete usage timing: 'Use this after a booking to remind the user what coverage their card provides on this rental.' It does not explicitly name alternatives or when-not conditions, but the stated purpose is clear enough to guide selection among the many sibling 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 convey read-only and non-destructive behavior, so the description adds value by explaining that the traveler completes the reservation on the web and that in-conversation booking via book_vehicle is partner-only. This clarifies the operational outcome beyond the schema and 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 wasted content: purpose, usage, and return/fallback context are each covered. It is front-loaded and efficiently structured, though the first and third sentences overlap slightly in describing the return 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?

For a read-only link-generation tool with a full input schema and an output schema present, the description is nearly complete. It covers what the tool returns, when to use it, and the key fallback condition. Minor details like authentication or link expiration are not addressed, but they are not essential for correctness.

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 five required parameters. The description adds general context by tying the parameters to search results but does not add parameter-level meaning beyond what the schema provides; the baseline 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?

Description states a specific verb and resource: getting a Gondola.ai deep link/checkout link for a specific vehicle from search results. It clearly distinguishes the tool from booking tools by emphasizing the returned artifact is a shareable web URL where the traveler completes the reservation.

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 says when to use it: to share a booking page URL for web completion, or as a fallback when in-conversation booking via book_vehicle is unavailable. It also names the alternative and the condition that selects it, which is strong usage 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 readOnlyHint=true and destructiveHint=false, and the description aligns with that by saying 'Get detailed information.' It adds behavioral context beyond annotations by specifying what categories of details are returned. Since an output schema exists, the description does not need to enumerate return fields.

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 first sentence states the core function directly, and the second provides workflow context and the content categories the agent can expect. Every word 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 detail tool with a full output schema, complete parameter documentation, and annotations covering safety, the description covers purpose, relationship to search_Vehicles, and the types of information returned. Nothing critical for selecting and invoking the tool 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 100%, so each parameter already has a clear definition such as 'Rate code from search results.' The description reinforces the workflow context by saying to use it after search_vehicles, but it does not add parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and a concrete resource ('detailed information about a specific rental vehicle option'). It also names the exact content areas (extras, insurance options, charges, cancellation policy) and positions the tool as the follow-up to search_vehicles, which distinguishes it from search and booking-focused siblings.

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 a clear trigger condition: 'Use this after search_vehicles to get extras, insurance options, charges, and cancellation policy for the vehicle the user wants to book.' It does not explicitly state when not to use it or name alternatives like get_vehicle_booking, but the workflow context is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint and destructiveHint false; the description reinforces this by saying 'Analyze' and adds useful behavioral context: it takes no arguments and works portfolio-wide rather than for a single trip. It could go further by noting any data assumptions or estimate caveats, but with annotations covering the safety profile, this is strong.

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: the first defines the core function and outputs, the second clarifies argument/scope, and the third handles usage routing. Every sentence earns its place and the most important action 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 a zero-parameter read-only analysis tool with an output schema and clear alternatives, this description covers selection, invocation, scope, and exclusion criteria completely. No missing detail would prevent an agent from calling it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the schema fully covers the input surface, so the baseline is 4. The description adds value by explicitly stating 'Takes no arguments' and explaining why (portfolio scope), which prevents an agent from trying to pass a trip ID.

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

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

The description opens with a specific verb and resource: analyze the user's entire loyalty portfolio and surface highest-value actions. It enumerates concrete outputs (expiring points ranked by value at risk, transfer opportunities, largest balances), which makes the tool's function unmistakable and distinguishes it from trip-booking tools like search_hotels.

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 trigger phrases ('how to make the most of their points, what's expiring, or where they can transfer') and a clear when-not-to-use rule with named alternatives (search_hotels / compare_rates for a specific trip). This is exactly the kind of routing an agent needs.

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 destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context by stating that it returns a confidence-scored label with supporting signals and price history, and that the prediction is based on historical trends rather than a guarantee.

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, each earning its place: what the tool does, when to use it, and what it returns. It is front-loaded with the core purpose and contains no filler or redundant restatement.

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, combined with full schema coverage, an output schema, and safety annotations, provides enough context for an agent to select and invoke the tool correctly. It could be slightly stronger by naming related alternatives or noting limitations, but nothing essential for basic invocation 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 100%, so the input schema fully documents all parameters and their meaning. The description does not add parameter-level detail beyond the schema, which matches the baseline 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 states the tool's function: predicting whether a current hotel rate is a good deal based on historical price trends. It is specific about the verb and resource, and the use-case framing helps separate it from generic rate lookup tools, though it does not explicitly name or contrast 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?

The description gives an explicit when-to-use condition: when the user is debating booking now versus waiting. This is clear and actionable, but it does not provide exclusions or alternatives such as when to use diagnose_rates or compare_rates instead.

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 include readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantive behavioral context beyond annotations: artist keywords are resolved and pinned, tribute/club nights are filtered out, namesake events must not be presented as the performer's own, price_precision 'rank_only' means amounts are withheld and only ranks are exact, and include_unavailable has specific semantics. This is rich behavioral disclosure that helps the agent avoid errors.

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 appropriately sized for a tool with 14 parameters and substantial edge cases. It front-loads the core purpose and return contents, then organizes guidance into clear, purposeful sentences covering pagination, artist resolution, namesake ambiguity, price_precision handling, and provider restrictions. Every sentence earns its place and adds actionable information.

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

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

For a search tool with 14 parameters, an output schema, and 71% schema coverage, the description covers the critical operational context: pagination, provider-specific behavior, ambiguous keyword handling, budget-question pricing guidance, and restrictions on parameter combinations. The output schema exists, so return-value details are not required in the description, and all major decision points an agent would face are addressed.

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 71%, and the description adds meaningful semantics for key parameters: it explains match_artist resolution behavior, sort=price provider limitations (no performer resolution, rejection when combined with attraction_id/include_unavailable), max_price's requirement for sort=price, and page pagination usage. It doesn't describe every parameter, but it clarifies the non-obvious ones beyond what the schema states.

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 ('Search for live events') and a concrete resource ('by artist, team, show, or event name'), and it distinguishes itself from travel/hotel/vehicle siblings by focusing on event discovery with dates, venue, status, price range, and canonical event page. It clearly communicates what the tool does and its scope.

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 explicit usage guidance: use page=0 first, increment page when more results are available; set match_artist=false when the keyword is not a performer; use sort=price for cheapest-first/budget questions; and use max_price only with sort=price. It also names when not to use certain options (e.g., price floor is not supported) and how to handle ambiguous performer names, giving clear 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?

Beyond the readOnly/openWorld/non-destructive annotations, the description discloses important behaviors: results are ranked by traveler loyalty/history rather than price alone, results are cash-priced and discovery-only, responses are paginated at 10 options, and award pricing may arrive asynchronously via pending_sources. These traits materially affect how an agent should interpret and act on the result, and none of them are visible from annotations alone.

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 front-loaded with the core action, then adds ranking behavior, pagination, booking limitation, and the points follow-up in tight, purposeful sentences. Every sentence earns its place and the length is justified by the tool's complexity. There is no filler or repetition of annotation values.

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 search tool with an output schema and readOnly/openWorld annotations, the description covers everything needed to call and interpret the tool correctly: what results look like, how pagination works, that booking is not possible, and what to do about pending award pricing. No critical operational context 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?

The input schema already has 100% parameter description coverage, so the baseline is 3. The description adds some flow-level context about page and points, but it does not add much parameter-specific meaning beyond what the schema already provides. Since the schema covers all parameter semantics, no compensation is needed and 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 opens with a specific verb and resource: 'Search for flights by route and date.' It clearly differentiates this tool from the other search_* siblings (hotels, vehicles, events) by domain, and from get_flight_points by stating that this search returns cash-priced discovery options while award pricing is handled by a follow-up call. The scoping to flights, date, and route is unambiguous.

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 usage guidance: pagination instructions ('Call again with page=2, 3, ...'), a discovery-only limitation ('cannot be booked through Gondola'), and a concrete conditional handoff to get_flight_points when pending_sources appears. It names the alternative tool and the exact condition that triggers it, so an agent knows when to use this tool versus the flight-points follow-up.

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/openWorldHint/destructiveHint annotations, the description discloses a key behavioral trait: 'This tool searches one fixed stay window.' It also specifies the return payload ('cash and points rates and deal scores') and the no-silent-default policy for flexible dates, giving the agent behavioral context the annotations alone do not provide.

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 front-loaded with the one-sentence purpose, then layers follow-up routing, a fixed-window constraint, and a flexible-window handling rule in a logical order. Every sentence addresses a distinct decision an agent will face, and there is no filler or restatement of schema content.

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 what the tool returns, how to branch to compare_rates and get_multi_night_rates, and how to handle ambiguous flexible-date requests. With a fully described input schema and an output schema present, nothing needed for correct selection or invocation 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?

All six parameters are fully described in the input schema (100% coverage), so the schema carries the parameter documentation burden. The description only echoes 'location and dates' and adds no parameter-level detail beyond what the schema already states, so the 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 opens with a specific verb and resource: 'Search for hotels by location and dates,' and states exactly what is returned (cash and points rates and deal scores). It also differentiates from sibling tools by explicitly naming compare_rates and get_multi_night_rates as follow-ups rather than describing the same function.

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 direct, actionable routing: use compare_rates for a cash-vs-points decision widget instead of narrating rates, and use get_multi_night_rates on top hotel_ids when the user wants alternate date options. It also provides a concrete rule for flexible stay windows (ask or pick and disclose, never silently default to earliest dates), leaving no ambiguity about when to use this tool versus 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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description adds useful behavioral context: results are sorted by price and include vendor, class, and rate details. This goes beyond the annotations and clarifies what the agent can expect from the tool. No contradiction with annotations is present.

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, efficient sentence with no filler. It front-loads the action ('Search for rental vehicles') and then provides essential output details. Every word contributes meaning, and it is appropriately sized for a search 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?

Given that the tool has an output schema, the description does not need to detail return formats. Annotations cover read-only and open-world behavior. The description covers sorting and result fields. The only notable gap is the airport/city ambiguity discussed under parameter semantics, but overall the description is fairly complete for this tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema provides full parameter documentation, setting a baseline of 3. However, the description says 'airport or city,' while the schema's pickup_location property explicitly restricts values to airport IATA codes. This potential discrepancy could lead an agent to pass a city name (e.g., 'Los Angeles') instead of an airport code, making the description more misleading than helpful.

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's function: 'Search for rental vehicles at an airport or city.' This is a specific verb-resource pair with an explicit output description: 'Returns available cars sorted by price with vendor, class, and rate details.' It distinguishes the tool from siblings like get_vehicle_details or get_vehicle_booking, which are about specific vehicles or bookings, not search.

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 no guidance on when to use this tool versus alternatives. There is no mention of using get_vehicle_details for a specific car or compare_rates for rate comparisons. The context is only that it searches rental vehicles, which is essentially the purpose, not usage 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 annotations, the description discloses that 'Entries are appended, so saving one preference never overwrites another,' which is important persistence behavior. It also provides real examples of acceptable and unacceptable entries, clarifying the expected effect of the operation.

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, front-loaded with the core purpose, and every sentence adds value: purpose, usage trigger, examples, exclusions, and append behavior. No filler or redundant detail.

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 single-parameter, append-only tool with schema coverage and annotations provided, the description fully covers what the agent needs: what to save, how to phrase it, what not to save, and the non-destructive nature of the operation. Nothing required for correct invocation 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?

The input schema already documents the single parameter thoroughly, including good and bad examples. The tool description adds further guidance about specificity and actionable entries, which reinforces but does not fully duplicate the schema content.

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 ('save') and resource ('learned travel preference or experience to the user's traveler profile'), making the tool's function clear. It also distinguishes itself from nearby read-oriented siblings like get_traveler_context by focusing on persisting preferences rather than retrieving them.

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 'Use when the user shares preferences, likes, dislikes, or trip experiences that should inform future recommendations' and gives concrete counterexamples. It also warns against saving temporary logistics like flight arrival times, giving the agent clear guardrails for when not to invoke the tool.

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