Award Travel Finder

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

With all annotation hints false, the description carries the burden of behavioral disclosure. It discloses the paid nature, the cost allocation rule across legs, and Gmail integration. It does not cover failure modes or idempotency, but the essential side effects (logging and cost distribution) are transparent.

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 coherent paragraph with no fluff. Each sentence adds value: purpose, award/cash distinction, multi-leg handling, Gmail hint, and paid warning. It front-loads the core action and methodically covers important edge cases.

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 18 parameters, 5 required, and no output schema, the description covers the critical semantics needed to log a booking correctly, especially the multi-leg and award/cash nuances. It doesn't explain every optional parameter or return behavior, but for a logging tool with clear schema patterns, it is sufficiently complete for its 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 only 39%, so the description must compensate. It clarifies the meaning of kind (award vs cash with example), trip_id's role in multi-leg grouping, and the first-leg cost rule for cash_paid and points_spent. It also hints at taxes_currency via the cash_paid description. Key parameters are well explained, though many optional ones (notes, passengers, confirmation_number) are left to 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 tool logs a flight booking/redemption, distinguishes award vs cash, and explains the multi-leg handling pattern. It explicitly names the alternate payment kinds and the per-leg call convention, making its purpose distinct from update/delete/list flight booking 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?

Provides explicit when-to-use guidance for multi-leg trips (call once per leg with same trip_id, put total cost on first leg), and mentions Gmail integration and paid feature. It does not explicitly contrast with update_flight_booking or when to modify existing bookings, but the core usage context is 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?

The description adds meaningful behavioral context beyond the annotations: award bookings include price-drop monitoring, cash bookings require kind and original_pay_rate_usd, and trip_id causes the stay to group with matching flights. It also discloses that this is a paid feature. No contradiction with annotations 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?

Four sentences convey the core purpose, parameter-critical guidance, workflow context, and a paid-feature warning without redundancy. The most important information, the award/cash distinction, is front-loaded, and every clause adds 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 12-parameter creation tool with no output schema and annotations that only report false hints, this description covers the essential workflow well: where IDs come from, required cash parameters, trip grouping, and email-based data extraction. It does not describe return values or duplicate-handling behavior, but the core call path is clear enough for an agent to proceed 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 only 50%, and the description compensates well for key gaps. It explains the award vs cash distinction for kind, the source of hotel_id, the purpose of trip_id, and how check-in/out dates, room type, rate, and confirmation number can be extracted from a Gmail reservation.

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: log a hotel booking to the user's portfolio. It clearly distinguishes this from sibling tools like add_flight_booking, update_hotel_booking, and delete_hotel_booking by stating the operation type and target resource explicitly.

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

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

It gives concrete sourcing guidance: use hotel_id from search_hotels or get_hotel_availability results. It also explains when to pass trip_id and how that affects grouping with flights. It does not explicitly name alternatives like update_hotel_booking for modifications, but the context strongly implies the intended workflow.

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

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

Annotations are all false, giving no safety hints, so the description carries the burden. It states this is a mutation ('Add') but does not disclose side effects, idempotency, failure modes, or what happens if the voucher already exists. The paid note and the prerequisite add some context but not rich behavioral detail; a 3 is appropriate.

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 no filler. The core purpose is front-loaded, the prerequisite is given, and the paid caveat is included. 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 simple add operation with one required parameter and no output schema, the description covers the essential workflow: what to do, how to get the slug, and that it costs money. Missing details like error handling or return values are minor given the simplicity and the well-specified schema.

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 75% (3 of 4 params have descriptions including format and examples). The description text adds only the instruction to use list_voucher_types to get the slug, which reinforces the schema rather than adding new meaning. With high schema coverage, baseline 3 is correct.

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 action (Add), the resource (companion/upgrade voucher), and the destination (user's inventory). It also distinguishes itself from siblings like 'apply_voucher_to_booking' and 'delete_voucher' by specifying the inventory add purpose, and mentions the prerequisite 'list_voucher_types' for finding the required slug.

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 concrete prerequisite ('Use list_voucher_types to find the voucher_slug') and explicitly flags it as a paid feature, giving the agent an important usage constraint. However, it does not explicitly state when not to use it or list alternative tools (e.g., 'apply_voucher_to_booking'), so it falls short of full exclusions.

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

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

Annotations provide no hints (all false), so the description bears the full burden. It discloses that the tool can apply or detach a voucher and that it is a paid feature, but does not mention side effects such as reversibility, impact on the booking, or error conditions. For a mutation tool with zero annotation coverage, this is a moderate but incomplete disclosure.

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 primary action and followed by the detach condition and paid-feature note. There is no fluff or repetition; every clause contributes to understanding the tool's 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?

For a relatively simple mutation with 3 parameters and no output schema, the description covers the core use cases: applying and detaching, with examples and a cost condition. It lacks explicit handling of error cases or return values, but those are not always required. The description is mostly complete for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already explains all parameters. The description adds some nuance with examples (voucher types) and reiterates the detach behavior for booking_id, but this is largely redundant with the schema. It does not provide additional meaning beyond what the schema offers, 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 clearly states the action 'apply' and the resource 'voucher to a booking', with specific examples (BA companion voucher, Barclaycard upgrade voucher) that differentiate it from generic booking tools. It also distinguishes from sibling tools like add_voucher or delete_voucher by specifying it affects existing bookings. The mention of 'detach' further clarifies its dual 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 implies when to use it: when you have a held voucher and want to attach it to a booking or detach it. It gives context with examples and notes it is a paid feature, which is a use condition. However, it does not explicitly compare to alternatives like add_voucher or list_my_vouchers, though the distinction is implied by the tool name and sibling set.

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 establish that this is a mutating, non-destructive operation. The description adds context that it groups existing bookings under a trip and affects portfolio display. It does not disclose what happens if a booking is already assigned to another trip, nor any other side effects, but the annotations cover the main safety profile.

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: purpose, ID sourcing, and optional-parameter handling. The most important information is front-loaded, and there is no redundancy 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?

For a three-parameter mutation tool with complete schema descriptions and non-destructive annotations, the description covers the essentials: what the tool does, where to get IDs, and how to treat optional arrays. It is slightly incomplete about reassignment behavior and whether calling again with the same bookings has any effect, but nothing blocks an agent from invoking 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%, yet the description still adds real value by explaining how to source each parameter's values and by clarifying that empty arrays or omission are acceptable for unused booking types. This directly informs correct parameter construction beyond the schema's terse 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 opens with a specific verb and resource: "File existing flight and/or hotel bookings under a workspace Trip." It also states the outcome, grouping bookings in the portfolio, which clearly differentiates this tool from adding new bookings or creating trips. The scope 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 tells the agent where to get the required IDs: trip id from list_trips / create_trip and booking ids from list_flight_bookings / list_hotel_bookings. It also explains how to handle booking types being moved versus omitted. It does not explicitly name sibling alternatives or exclusion conditions, 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful non-obvious context beyond the annotations: the output shape (a finding list with a chain-aware dispute template) and the premium-tier access requirement. It does not disclose edge-case behavior such as handling of unsupported chains or malformed folio text, but the added context is meaningful.

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: the core purpose, the supported scope, and the deliverable/access tier. The most important information is front-loaded, with no filler.

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

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

The description is sufficient for a basic invocation since the two required parameters (chain and folio_text) are implicitly documented, and the output shape is described despite there being no output schema. However, the three optional parameters remain unexplained at 0% schema coverage, and the relationship to audit_marriott_folio is unaddressed, leaving clear gaps for a tool of this 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 description coverage is 0%, so the description must compensate, but it only partially does. It implicitly documents chain (by listing the four supported chains, matching the enum) and folio_text (by referencing 'hotel folio'), yet stay_type, status_tier, and confirmation_number receive no explanation at all, leaving three of five parameters semantically opaque.

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 ('audit'), a resource ('hotel folio'), and a clear purpose ('commonly-disputable charges'), and enumerates the supported chains (Marriott, Hilton, Hyatt, IHG). It is clear and unambiguous, though it does not explicitly differentiate itself from the sibling audit_marriott_folio, which an agent might reasonably confuse it with.

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

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

There is no guidance on when to use this tool versus alternatives. The description never mentions audit_marriott_folio, despite that sibling covering one of the same chains, nor does it state any conditions that would favor one tool over the other. 'Premium tier' hints at an access restriction but does not function as 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 establish read-only, non-destructive behavior. The description adds that the tool returns a finding list with a dispute template and notes the premium-tier requirement, which is useful beyond the annotations. It does not conflict with the readOnlyHint or describe unwarranted side effects.

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 compact sentences carry scope, examples, and output in a front-loaded way; 'Premium tier' is the only separate fragment. There is no repetition of schema fields or annotation 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 read-only audit tool, the description covers the resource, purpose, and high-level return shape. Gaps remain: no parameter semantics for three optional fields, no explicit distinction from audit_hotel_folio beyond the brand name, and no output schema to make the 'finding list' structure precise.

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 0% schema description coverage, the description needed to compensate, but it only implicitly covers folio_text via 'folio' and hints at stay_type through 'award stays'. status_tier and confirmation_number are never mentioned, and there is no guidance on how the optional enums affect the audit.

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

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

States a specific verb ('audit'), a clearly bounded resource ('Marriott Bonvoy folio'), and identifies the exact class of charges it examines. The examples and return description make it distinct from the sibling audit_hotel_folio by brand and specialized 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 implies the use case: auditing a Marriott Bonvoy folio for disputable charges. It does not explicitly state when to prefer this over audit_hotel_folio, nor does it give exclusions or conditions such as 'for non-Marriott folios use audit_hotel_folio'. That leaves the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral distinctions between revenue-based and distance-based earning and commits to returning great-circle distance. It doesn't describe output shape, rounding, or exactness, but for a non-mutating estimator with read-only annotation, that is a minor gap.

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

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

Three compact sentences; the core purpose and supported programs are front-loaded, followed by usage examples and provider slug guidance. No filler or restatement 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?

Given 7 parameters, 3 program-specific calculation rules, and no output schema, the description is nearly sufficient: it covers the inputs that matter, the program slugs, and the main output (points + distance). It could add a note that returned values are estimates and maybe rounding, but those are not required 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?

Schema coverage is 100%, so the description doesn't need to repeat definitions. It adds meaning by tying fare_price and segments to specific programs ('revenue-based (pass fare_price)' and 'Flying Blue XP is fixed per segment'), and gives program slugs and currency examples. This is a meaningful increment over 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 opens with a specific verb ('Estimate'), a precise resource (elite-qualifying points a flight earns toward status), and the return of great-circle distance. It gives concrete example questions and names the exact programs, so an agent can identify what it computes. However, it never names a sibling such as get_earning_rates or get_program_rates, so differentiation from those is implicit rather than explicit.

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 clear conditional usage: pass fare_price for revenue-based BA/AA programs, while Flying Blue XP is fixed per segment by distance and cabin. The example questions ('LHR–JFK in business?', '£600 fare?') establish realistic invocation contexts. It stops short of saying 'use X instead when...' or listing exclusions, so it provides clear context without explicit alternatives.

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

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

The description goes well beyond the annotations by adding specific post-invocation behavior: 'Cancelled monitors stop firing but are preserved for history.' This clarifies that despite destructiveHint=true, the data is not deleted and remains available historically. This is valuable context that 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?

Two short sentences with no filler. The action is front-loaded and the key behavioral nuance about preservation is stated as a separate clarifying clause. 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 single-parameter mutation tool with no output schema, the description covers the precondition (active), the action (cancel by ID), and the outcome (stops firing, preserved). It is nearly complete, though it could have mentioned how to discover the monitor_id via list_route_monitors or what happens for unknown IDs.

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 0% schema description coverage, the description is the only source of parameter meaning, but it only says 'by ID.' It does not explain where monitor_id comes from, what constitutes a valid monitor_id, or what happens if an invalid or already-cancelled ID is supplied. This leaves the agent to infer too much for the sole parameter.

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 ('Cancel') and names the precise resource ('route monitor'), with an explicit identifying scope ('by ID'). It also differentiates the behavior from related sibling tools by explaining that cancelled monitors stop firing but remain preserved, making it distinct from a delete operation or an update.

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 'active route monitor' establishes a clear precondition, and the consequence 'stop firing' explains what happens after the call. However, it does not explicitly mention alternatives, such as using update_route_monitor to modify a monitor or list_route_monitors to find a monitor ID, leaving some routing to the agent implicit.

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 say destructiveHint=true, but the description adds a valuable nuance: the record and its last result are preserved. This clarifies the real impact of the cancellation beyond the generic destructive hint and helps the agent set expectations.

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

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

Two short sentences convey the action, the consequence, and the retention behavior with no filler. The most important 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 simple one-parameter cancellation action, the description tells the agent what happens and what is preserved. It could mention error behavior or the source of the ID, but the tool's low complexity makes the definition reasonably complete.

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

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

The single parameter standing_order_id is mentioned indirectly through 'by ID', but the description adds little beyond the schema's property name and type. With 0% schema description coverage, there is minimal compensation, though the parameter is simple and self-explanatory.

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 ('Stop') with a clear resource ('standing order by ID') and states the outcome ('so it no longer runs'). It also clarifies the record is retained, which distinguishes it from deletion tools and other standing-order operations.

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

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

The description implies the right context: use this when you want a standing order to stop running but still keep its history. However, it does not explicitly name alternatives like list_standing_orders or explain when not to use this tool, 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 indicate destructiveHint=true and readOnlyHint=false, but the description does not disclose any side effects or confirm whether this tool modifies data. It only describes an estimation and ranking process, which seems inconsistent with the destructive hint. The description adds no behavioral context beyond what annotations provide, leaving ambiguity about side effects.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and mentions the net annual fee inclusion. It is concise with no redundant 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?

The tool has 4 parameters and no output schema, so the description should clarify the return format. It states that it ranks cards and includes net annual fee, which gives some idea, but it does not mention the default region or the optional limit and card_type parameters. It also fails to address the destructive hint from annotations, leaving potential side effects unclarified.

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

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

The schema covers 75% of parameters with descriptions (limit, region, monthly_spending), but card_type lacks a description. The tool description does not elaborate on any parameter, merely referencing 'monthly spending' which matches the required parameter. It adds no meaning beyond the schema, so it does not compensate for the missing card_type description.

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

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

The description clearly states the tool's function: given monthly spending, it estimates annual rewards for each card and ranks them. It also mentions including net annual fee after benefit credits, which adds specificity. This distinguishes it from siblings like cards_compare_cards and cards_rank_welcome_bonuses by focusing on annual rewards ranking based on spending.

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

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

The description implies usage when the user has monthly spending data and wants to see which card yields the best annual rewards. However, it does not explicitly state when to use this tool versus alternatives like cards_compare_cards or cards_find_cards_for_category, nor does it provide any exclusions or conditions for alternative 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?

The annotations declare destructiveHint=true, implying the operation may modify or destroy state, while the description describes a pure comparison operation that reads cards side by side. This is a direct contradiction between the described behavior and the annotation, and no additional context is provided to resolve it.

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 no filler: the core function and scope are front-loaded, and the data-source instruction is compact and directly actionable.

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 comparison tool, the description provides enough detail about what to pass and what dimensions are compared. The absence of an output schema is acceptable, but the contradiction with the destructive hint prevents a perfect completeness score.

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 ids array with min/max constraints and an example. The description adds the practical instruction to source ids from list_cards, which helps the agent construct valid input beyond what the schema provides.

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

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

The description opens with the verb 'Compare' and names the resource ('2–4 cards') plus the specific comparison dimensions (annual fees, welcome bonuses, top multipliers, total benefit credits). It also names the data source (list_cards), making it clearly distinct from sibling card tools like cards_rank_welcome_bonuses.

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 invocation context by instructing the agent to pass card ids from list_cards and by enumerating the exact comparison dimensions. It does not explicitly mention alternatives or when not to use the tool, but the purpose is clear enough to guide selection.

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 openWorldHint=true and destructiveHint=true, suggesting the tool may have side effects or return broad results, but the description does not explain these. No mention of caching, data sources, or potential mutation behavior. The description is silent on behavioral nuances; only order by multiplier is mentioned.

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?

Description is two sentences, concise, and front-loads the core purpose. No fluff, but it ends with sorting detail that could be merged with first sentence. Overall efficient.

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

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

With no output schema and moderate param coverage, the description covers the main use case but misses potential filters (region, card_type) and does not clarify open-world or destructive hints. For a search tool, it is usable but not fully complete.

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

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

Schema has 60% coverage, with descriptions for category, limit, and min_multiplier, but not for region and card_type. The description adds context that category supports UK/AU terms, which is covered in schema, but does not add much beyond schema. Region and card_type enums are self-explanatory, so baseline 3 is adequate.

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

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

Description clearly states the tool finds cards with best earning multiplier for a spend category, with specific examples. Distinguishes from sibling tools like cards_compare_cards (comparison) and cards_analyze_spending (analysis).

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

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

Description implies usage for finding top earning cards per category, but does not explicitly mention when to use this vs cards_compare_cards or cards_list_cards. No exclusions or alternatives given, though purpose is clear enough for moderate 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?

The description describes a read-only lookup ('Find which...'), but the annotations declare destructiveHint=true and readOnlyHint=false. This is a direct annotation contradiction, so the description fails to provide a consistent behavioral profile.

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 tight sentences with no filler. The first states the core function, the second adds the optional region filter, and the wording is front-loaded and directly actionable.

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 simple two-parameter lookup, and the description conveys the intended inputs and optional filter. However, with no output schema, no usage guidance, and an annotation contradiction, an agent is not fully equipped to know the response shape or when to choose this tool over siblings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds very little beyond the schema: it restates 'airline or hotel' and mentions the region filter, but provides no additional formatting, matching, or default behavior 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 ('Find which transferable points programs can transfer to a given airline or hotel') and an optional region filter, so an agent can tell what resource is queried. However, it does not explicitly distinguish this from sibling tools like cards_list_transfer_partners or find_transfer_paths.

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

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

There is no guidance about when to use this tool versus alternatives. Nearby sibling tools such as cards_list_transfer_partners, find_transfer_paths, and compare_transfer_options exist, but the description does not explain how this one differs or when it should be preferred.

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 declare destructiveHint=true, while the description describes a pure read operation ("Get full details"). This is a direct contradiction, making the tool's safety profile untrustworthy. No other behavioral traits are disclosed, and the contradiction prevents the description from providing reliable 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 description is one front-loaded sentence with no filler. Every clause adds specific information about what details are returned, making it efficient and well-structured.

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 one-parameter getter, the description covers the operation, object, and key return content, which is mostly sufficient. However, the contradictory destructiveHint annotation and the lack of any note about safety or return format leave the overall definition internally inconsistent.

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 is fully covered by the schema, including an example value and guidance to use list_cards to discover ids. The description adds no parameter-specific semantics beyond indicating the id selects a single card, 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 verb and object: "Get full details for a single card," and enumerates the delivered content (multipliers, benefits, welcome bonus, source URL). This clearly distinguishes it from list, compare, and rank 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 main description gives no explicit when-to-use guidance, but the id parameter's schema description provides a useful workflow cue: "Use list_cards to discover ids." This implies this tool is the detail-retrieval step after listing, but it does not explicitly exclude alternatives like cards_compare_cards.

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

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

The description presents the operation as a harmless read-only listing, but annotations mark destructiveHint=true and readOnlyHint=false, implying a destructive or mutating effect. The description neither acknowledges nor explains this, and it directly contradicts the destructive annotation by framing the tool as a simple 'List' operation. This is a clear annotation 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?

Two sentences with no filler: the first states the action and scope, the second summarizes the return payload and routes to the full-detail sibling. Information is front-loaded 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?

The return summary fields are listed, the main alternative is named, and filters are covered by the schema. However, the destructiveHint=true annotation introduces serious ambiguity that the description does not resolve, and with no output schema or pagination/limit guidance, the description is not fully complete for safe invocation.

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

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

Schema description coverage is 100%, with all three optional filter parameters already documented (region, provider, card_type). The description adds no additional parameter-level meaning, so the 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-resource pairing ('List credit cards in the database') and clearly differentiates from cards_get_card by stating it returns compact summaries and pointing to get_card for full details. This leaves no ambiguity about what the tool does or how it relates to the closest 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?

It explicitly directs agents to use `get_card` when full details are needed, providing a clear alternative. It does not enumerate other sibling distinctions (e.g., when to use cards_find_cards_for_category), but the core routing guidance is present 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 declare destructiveHint=true and readOnlyHint=false, yet the description says 'List recent card data changes', which strongly implies a read-only operation. The description does not disclose any destructive behavior and directly contradicts the annotations, creating a serious risk that an agent misjudges the tool's side effects.

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 resource, and the second supplies a natural-language use case. The phrase 'what changed recently?' is somewhat redundant with 'recent' and 'changes', but it still helps an agent recognize matching queries.

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

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

The tool has no output schema, and the description only says 'list' without describing the shape or content of results beyond the examples of change types. More importantly, the destructive annotation is left unexplained, so an agent cannot tell whether invoking this tool mutates data. This is a significant completeness gap.

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

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

The input schema already provides complete descriptions for all three parameters (days, limit, card_id), including defaults and filtering semantics. The description adds little beyond the word 'recent', but because schema coverage is 100%, no compensatory parameter detail is required.

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

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

The description opens with the action 'List recent card data changes' and enumerates the domain via examples such as welcome bonus updates, fee changes, and multiplier edits. This clearly identifies the card-data-changes resource and distinguishes it from sibling tools like cards_list_cards or cards_analyze_spending.

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 it is useful for 'what changed recently?' queries, which gives an agent a concrete trigger for choosing this tool. However, it does not provide when-not-to-use guidance or name alternative tools, so it misses the explicit exclusions needed for 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?

The description says 'List', implying a read-only operation, while annotations declare destructiveHint=true and readOnlyHint=false. This is a direct contradiction. The description also provides no behavioral detail that would explain any side effects or state changes, so the agent is left with conflicting signals.

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 no filler. The main action is front-loaded, and the region example is concrete and useful. Every word contributes.

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 list tool with no output schema, the description gives a reasonable overview, but it completely omits any mention of the destructive/read-write behavior implied by the annotations. It also doesn't describe response format or what happens when filters are combined. The contradiction makes the context incomplete and potentially misleading.

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 description adds real meaning to the region parameter with an example, but provider is already documented in the schema and partner_type is left to its enum values. With schema description coverage at 67%, the description partially compensates but does not fully describe all parameters.

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 ('List') and resource ('transferable points programs and their airline/hotel partners'), which makes the tool's function immediately clear. It also differentiates from nearby siblings like cards_find_transfer_programs_for_airline by focusing on listing programs and partners rather than finding a transfer path.

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 for when the region filter is useful, including a concrete example. It does not explicitly state when to prefer this tool over siblings like cards_find_transfer_programs_for_airline or compare_transfer_options, but the listing intent is clear enough for basic routing.

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

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

The description presents a read-only listing operation, but annotations mark it as not read-only and destructive (readOnlyHint=false, destructiveHint=true). That is an annotation contradiction, and the description provides no caveat or explanation. It also does not mention what is returned for each bonus or how pagination behaves.

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

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

The description is a single front-loaded sentence that moves immediately from action to resource to sort order, with no filler or repetition.

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

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

For a 5-parameter tool with no output schema, the description gives no sense of the return fields, and the contradictory destructive annotation is unresolved. The optional filters and the dynamic 'current' nature (openWorldHint) are partially covered, but the missing output shape and safety ambiguity leave a substantial gap.

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

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

With 60% schema coverage, the description usefully reinforces the point/mile value theme and the spend achievability filter, aligning with min_value and monthly_spend. However, region and card_type have no schema descriptions and the description does not clarify them, and 'spend achievability' is vaguer than the schema's monthly_spend formula.

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 identifies a specific resource ('current welcome bonuses'), a concrete action ('List'), and a clear ordering ('sorted by point/mile value descending'). It is unambiguous, but it never explicitly separates itself from sibling tools such as cards_list_cards or cards_compare_cards, so it stops short of full differentiation.

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

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

The only usage hint is the optional spend filter; the description does not say when to choose this tool over siblings like cards_compare_cards or cards_find_cards_for_category, and it gives no exclusions or situational guidance. This leaves the agent to infer the intended use case from the name.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral details beyond that: it ranks by real cash cost, includes multi-hop routes, active bonuses, and transfer posting times. This gives agents useful expectations about what the tool computes, though it does not describe output format or edge cases.

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 purpose and then details. Every phrase adds value: the ranking criteria, inclusion of multi-hop and bonuses, and the premium tier note. No redundancy or 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 read-only tool with clear inputs and no output schema, the description covers the core behavior: what it ranks, the criteria, and the inputs. It omits details like return format or pagination, but the annotations cover safety and the purpose is clear. Given the tool's complexity, it is reasonably 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% with clear explanations for both points_needed and target_program. The description does not add much beyond confirming their role in the ranking, so it meets the baseline of 3 without exceeding it.

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

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

The description clearly states a specific action: deciding which points to use for a specific redemption. It specifies inputs (target program and points needed) and outputs (ranking of transfer routes by cost). It distinguishes itself from siblings like find_transfer_paths by emphasizing cost ranking and decision-making, not just path discovery.

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

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

The description implies usage context: when you need to choose among transfer options for a given redemption. It mentions 'Premium tier', indicating a prerequisite. However, it does not explicitly state alternatives or when not to use it, such as pointing to find_transfer_paths for just listing routes without cost analysis.

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 what the annotations state, the description reveals that the tool alone does not complete the connection: it returns a URL the user must open in a browser to grant access. It also discloses the initiating side effect and the dependency on a connection_required state.

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, purposeful sentences: action and resource, return value/user step, and trigger condition. There is no redundant or filler 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?

For a one-parameter tool with no output schema, the description covers the invocation trigger, the return value, and the required user action. An agent has what it needs to call the 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%, and the single provider parameter already has an enum and a description. The tool description adds no meaningful parameter semantics beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific action ('Initiate the OAuth flow') and a clear resource ('external integration'), and states it returns the authorize URL. This clearly distinguishes it from sibling tools like disconnect_integration and list_integrations.

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 gives a trigger condition: 'Use this when a tool returns connection_required.' This is strong context, but it does not mention when not to use the tool or name alternatives such as disconnect_integration or list_integrations.

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

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

The description adds meaningful behavioral context beyond the annotations: the 6-hour check cadence, email notification behavior, and the free/Premium account limit. It does not define what 'fresh availability' means or what happens if the user exceeds the monitor limit, but it provides substantial insight into how the tool behaves.

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

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

Two sentences, front-loaded with the core action, followed by high-value behavioral and account-limit context. There is no filler or redundant restating 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?

Given 8 parameters, 4 required fields, low schema coverage, and no output schema, the description is too thin. It omits parameter-level semantics, the meaning of 'fresh availability', duplicate/limit behavior, and what the operation returns or whether it can be reversed.

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 only 25%, so the description must compensate, but it only groups concepts as 'route + window + cabin' and does not explain origin/destination format, date format, max_points, passengers, or airlines. It is also slightly misleading because cabin is optional in the schema yet described as a standard matching criterion.

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

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

The description states a specific verb and resource ('Create a saved route monitor') and explains the monitor's ongoing behavior: checking every 6 hours, matching route/window/cabin, and emailing on fresh availability. This clearly distinguishes it from related siblings like update_route_monitor, cancel_route_monitor, and list_route_monitors.

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 usage is implied: use this when the user wants a saved monitor for award seats, rather than a one-time search. However, it does not explicitly name alternatives or state when not to use this tool versus search_availability or fs_create_seat_alert.

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 sparse annotation block, the description discloses meaningful behaviors: the order runs unattended, the result is emailed, the prompt executes with no conversation history, and the feature is Premium-only. These are exactly the operational constraints an agent needs and 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 core action and then uses two illustrative examples that directly clarify the prompt requirement. Every sentence earns its place, and the 'Premium only' restriction is included without padding.

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

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

For a creation tool with 5 parameters and no output schema, it covers the essential context: what the order does, how the result is delivered, prompt requirements, and access restriction. It does not describe the immediate API return value, which would have made it fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value on top by explaining how to write the required prompt: complete, self-contained, explicitly naming routes/programmes/cabins/dates. This is genuinely useful guidance beyond the schema's short 'self-contained instruction' note.

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 action ('Save a recurring instruction'), the resource (a standing order ATF runs), and the behavior ('then emails the result'). It is easily distinguished from siblings like cancel_standing_order and list_standing_orders by focusing on creation and the recurring, unattended execution model.

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 clear usage context: 'Use for anything the user wants checked repeatedly without asking', plus two concrete examples that help an agent recognize the right scenario. It does not explicitly name alternatives or state when not to use it, 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 already signal a non-read-only, non-idempotent mutation. The description adds useful behavioral context by explaining what a trip contains and the active-trip limit. It does not disclose what happens when the limit is exceeded, whether duplicate names are allowed, or what the response will look like.

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 concise sentence. It front-loads the action, gives a compact clarifying definition, and includes a relevant account-limit caveat with no redundant wording.

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 create operation without an output schema, the description explains the resource and one business rule. Still, it omits the return value, failure behavior when the active-trip limit is hit, and how this tool relates to post-creation steps such as assign_bookings_to_trip.

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 only 50%, with start_date and end_date lacking descriptions. The tool description does not compensate by explaining any parameters; it only clarifies the trip concept and account limit. Name and destination are described in the schema, but the date parameters receive no added semantic guidance.

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

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

The description states a specific verb and resource: 'Create a new trip', and defines the resource as 'a project workspace grouping chats, searches, monitors, and bookings.' This definition distinguishes create_trip from related siblings like list_trips, delete_trip, and plan_trip.

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

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

The description implies when to use the tool—when a new project workspace is needed—and adds a concrete constraint about free accounts having one active trip with extra trips requiring Premium. However, it does not explicitly mention alternatives or conditions where another tool should be used 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 carry destructiveHint=true and readOnlyHint=false; the description adds the trigger scenarios and the 'tracked' qualifier. It does not disclose side effects (e.g., impact on trips, reversibility), so it adds modest value beyond annotations.

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

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

Two sentences, no fluff, action first then usage conditions. Every phrase carries 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?

The tool is simple (one required param, no output schema), and the description covers what triggers it and what it acts on. It omits side effects or confirmation behavior, but the destructive annotation partially covers the risk profile.

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

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

Schema description coverage is 0%, so the description needed to explain how to identify the booking, but it never mentions booking_id or provides any additional parameter context. The single parameter is only documented by its name and integer type.

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

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

States the specific operation (cancel/remove) and resource (tracked flight booking), with concrete trigger examples ('cancelled, superseded, no longer happening'). Clearly distinguishable from sibling delete_hotel_booking or delete_trip.

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

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

Provides explicit user-intent conditions ('when the user says...') that trigger this tool. Does not name alternatives or exclusions, so not a full 5, but the guidance 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 destructiveHint=true and readOnlyHint=false, so the description is not required to restate the destructive nature. It adds some context ('tracked', 'portfolio') and the reason for use, but does not disclose additional behavioral traits such as irreversibility, cascading effects, or success/return behavior.

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

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

Two short sentences convey both the operation and the usage context with no filler. The core action is front-loaded, and every clause earns its place.

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

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

For a single-parameter destructive tool with clear annotations, the description covers purpose, target, and usage scenarios. It does not specify side effects on related trips or bookings, but that level of detail is not essential for invoking this tool correctly given its simplicity and the annotation profile.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining booking_id. It never explicitly mentions the parameter, how to obtain it, or what it references beyond the general notion of a 'tracked hotel booking.' The property name and integer minimum do some work, but the description fails to compensate for the missing schema descriptions.

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

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

The description uses a specific verb ('Remove') with a clear resource ('tracked hotel booking') and scope ('from the user's portfolio'). This clearly distinguishes it from related siblings like delete_flight_booking or delete_trip, and the first sentence fully states the operation.

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: 'when the trip is cancelled or the booking was added by mistake.' It does not explicitly name alternatives or exclusion cases, but for a single-purpose delete tool tied to one resource, the usage context is clear and 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 mark destructiveHint=true, so the destructive nature is known. The description adds useful context beyond annotations: it is a 'Paid feature' (cost/authorization implication) and only affects visits the user logged, not shared records. It does not detail irreversibility, but that is already signaled by destructiveHint.

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, each contributing: the action, how to find the id, and the paid-feature caveat. No filler or restatement of the tool name.

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

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

For a one-parameter destructive operation with no output schema, the description plus annotations fully equip the agent: it names the action, the source of the id, the prerequisite, and the paid restriction. Nothing important appears 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 schema already describes visit_id as 'Id of the logged visit, from list_lounge_visits,' covering 100% of parameters. The description reinforces this by telling the agent to use list_lounge_visits to find the id, but adds no new semantic detail 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?

States a specific verb ('Remove') and resource ('lounge visit'), and ties it to a prior action ('previously logged with log_lounge_visit'), so an agent knows exactly what this tool does. It clearly distinguishes from logging and listing, though it doesn't address the similarly named sibling lounge_delete_visit.

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

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

Gives explicit instruction to call list_lounge_visits to obtain the visit_id, showing the prerequisite step. It also scopes usage to visits 'previously logged with log_lounge_visit,' implying it is not for arbitrary lounge records. However, it does not mention the near-duplicate sibling lounge_delete_visit or state when to prefer one over the other.

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 destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds the context that the action targets a 'tracked' status and offers a concrete example, but does not elaborate on consequences (e.g., irreversibility, impact on related data). With annotations in place, this is acceptable but not richer.

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 sentence that is front-loaded with the core action, includes a useful example, and contains no redundant words. It is appropriately concise and well-structured.

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

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

For a destructive operation with an undocumented parameter, the description is under-specified. The lack of any explanation of 'program' is a significant omission, and the description does not cover prerequisites or side effects, making it incomplete for safe and correct usage.

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 has one required parameter 'program' with no description (coverage 0%). The description does not mention this parameter at all, providing no guidance on what values it expects (e.g., program name). The description completely fails to compensate for the schema gap, leaving the agent without essential information to call the tool correctly.

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

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

The description clearly states the verb ('Remove') and resource ('a tracked elite/loyalty status'), and includes an example of when to use it ('when it lapses and the user doesn't want to renew it'). This unambiguously identifies the tool's purpose and distinguishes it from sibling tools like set_loyalty_status.

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 specific usage scenario ('when it lapses...'), giving clear context for when to invoke the tool. However, it does not explicitly contrast with alternatives (e.g., 'use set_loyalty_status to add/update') or state when not to use it, missing an opportunity to fully differentiate from 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds useful context like 'Paid feature' and real-world scenarios, but does not disclose what happens beyond the removal, such as whether the deletion is permanent or affects related data.

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 no filler. The core action is stated first, followed by practical examples, the source for the parameter value, and the paid-feature warning. 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 simple one-parameter destructive tool with full schema coverage and annotations, the description covers what, when, how to identify the program, and the paid constraint. No output schema exists, so explaining return values is unnecessary.

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 documents 'program' as the loyalty program name as shown by list_points_balances. The description mostly restates this same guidance, so it adds no significant new parameter meaning 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?

Description uses a specific verb 'Remove' and resource 'loyalty program from your points balances', immediately distinguishing it from updating or listing balances. The examples clarify exactly what kind of removal is intended.

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

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

Gives clear context on when to use the tool ('closed the account or added it by mistake') and tells the agent to reference list_points_balances for the program name. It does not explicitly mention when not to use it or point to update_points_balance as an alternative, 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 already flag destructiveHint=true, and the description goes further by explaining that archiving keeps the trip and itinerary, and that bookings, monitors, and chats are always preserved and simply unfiled. It also clarifies that permanent deletion removes the itinerary for good, adding meaningful behavioral context 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?

The description is two sentences, front-loaded with the core purpose, and every clause adds decision-relevant information about the two deletion modes. There is no filler or redundant restating of the tool name.

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

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

For a destructive tool with two modes, the description explains both outcomes and the fate of associated records, and the schema covers the parameters. It does not describe return values or error behavior, but with no output schema and only two simple parameters, it is largely sufficient.

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 both parameters fully, including the default false for permanently. The description reinforces the permanently semantics but adds little beyond what the input schema provides, 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 states a specific verb and resource ('Archive a trip, or delete it permanently') and clarifies the two modes. It does not explicitly differentiate from sibling deletion tools, but the trip scope is evident.

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 clear context for choosing between archiving and permanent deletion: archiving frees the active-trip slot while retaining the trip, while permanent deletion removes the trip and itinerary for good. It does not explicitly name alternatives or exclusion cases, so it falls 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 destructiveHint=true, and the description's 'remove' aligns with that. The description adds the scope 'from the user's inventory', which is useful, but it does not disclose permanence, side effects, or preconditions. This is acceptable given annotations cover the destructive behavior.

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

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

A single, well-structured sentence. It is appropriately sized for the tool's simplicity and conveys the core action immediately without any 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 single-parameter destructive tool with annotations covering the danger profile, this description is largely complete. An agent can infer the required voucher_id and the inventory scope. It lacks explicit mention of return behavior or failure modes, but those are not essential for this simple operation.

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

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

Schema description coverage is 0%, so the description carries the burden of parameter meaning. The description does not explain voucher_id, how to obtain it, or its role beyond the schema's property name and type. With only one self-explanatory parameter, the gap is minor, but the description does not compensate for the zero coverage.

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

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

The description uses a specific verb ('remove'), a clear resource ('voucher'), and a precise scope ('from the user's inventory'). This clearly distinguishes it from related siblings like add_voucher, list_my_vouchers, and apply_voucher_to_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?

No guidance is given on when to use this tool versus alternatives, nor any exclusions (e.g., what happens if a voucher is already applied to a booking). The context of 'user's inventory' is implied but no explicit usage direction is provided.

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?

Although destructiveHint=true already signals danger, the description adds specific context about what is destroyed ('OAuth tokens are deleted from ATF storage'), which is exactly the kind of beyond-annotation detail needed. The wording also implies irreversibility.

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

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

Two short sentences with no filler, and the core verb and object are front-loaded. Every word contributes to understanding the tool's function.

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 one-parameter destructive tool with no output schema, the description plus annotations cover what the tool does, what it destroys, and the precondition for use. 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 0% schema description coverage, the description carries some burden, but the single provider parameter is constrained and self-explanatory via the enum. The phrase 'previously connected integration' helps the agent select a provider that is already linked, which adds value over the raw 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 uses a specific verb ('Revoke') and resource ('previously connected integration'), and adds that OAuth tokens are deleted, making the operation unambiguous. The contrast with sibling tools connect_integration and list_integrations is clear from the description itself.

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?

'Previously connected' states the precondition for use and implies the tool should not be used for new integrations. It does not explicitly name alternatives, but the sibling set makes the distinction obvious.

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 openWorldHint, so the description adds meaningful context beyond them: this tool returns a list of complementary remote MCP servers with one-line install URLs. It does not misrepresent side effects; the 'add to your client' phrasing refers to user action, not tool mutation.

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 no filler. The first sentence establishes what the tool does and returns, and the second provides immediately matchable trigger phrases.

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 parameterless, read-only discovery tool with no output schema, the description sufficiently covers what it returns, why it exists, 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?

The tool accepts zero parameters, and schema coverage is 100%, so there is nothing for the description to add about individual parameters. The parameterless-tool 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 names a concrete action ('discovers/lists') and a concrete resource ('other flight & travel MCP servers'), then scopes the content to seatmaps, airport delays/waits, and lounges with install URLs. This is specific enough to distinguish it from the fs_ and lounge_ discover siblings by category 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 gives explicit call triggers: seat selection, airport delays/security waits, baggage rankings, lounges, and the umbrella question 'what other flight tools are there?'. It does not explicitly name sibling discovery tools as alternatives or state when not to use it, so it is strong but not maximally 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 cover the read-only and non-destructive safety profile, so the description does not need to restate that. It adds useful context about program-stacked benefits but does not disclose behavioral details such as result format, filtering behavior beyond program, or whether it only returns premium properties without booking side effects.

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 core resource and programs are front-loaded, followed by the concrete benefit and a clear usage trigger. Every sentence contributes to selection and invocation.

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 low complexity, optional params, and existing schema/annotations, the description is essentially complete for an agent to invoke correctly. A minor gap is not mentioning the field filter option or result expectations, but these are not critical for a simple read-only search tool.

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

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

The input schema has 100% description coverage for both params, so the schema already explains city and program defaults. The description adds program meanings and benefits but does not need to compensate for schema gaps; 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 clearly states the verb 'Find' and the specific resource: Amex FHR, Amex THC, and Chase Edit hotels in a city. It also gives the value proposition of premium portal-stacking benefits, which further distinguishes it from generic hotel search tools.

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

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

Explicitly indicates when to use: 'when the user wants premium hotel options that maximize portal stacking.' It does not explicitly list alternatives or when not to use it, but the intended context is clear enough for an agent to route 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 readOnly (readOnlyHint=true) and non-destructive. The description adds useful behavioral context: it applies live transfer bonuses and computes source points needed, which goes beyond the structured hints. It doesn't describe side effects (none expected) or rate limits, but for a read-only lookup this is adequate.

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: purpose, key features, and usage trigger. It is front-loaded with the core function and avoids any fluff. Every sentence adds information, and the structure is easy to scan.

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?

There is no output schema, so the description should clarify what the tool returns. It mentions 'computes source points needed' but doesn't detail the structure of the returned routes (e.g., intermediate programs, transfer ratios, bonus details, or sorting). It also doesn't mention error handling (e.g., no routes found). Given the tool's moderate complexity, this is a notable gap, making the description adequate but incomplete.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds marginal value by tying 'points_needed' to the output of 'source points required' and by referencing multi-hop in the context of 'max_hops'. However, it doesn't introduce new semantics or syntax beyond what the schema already provides, 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 clearly states the tool's function: finding direct and multi-hop transfer routes between points programs, with a concrete example. It distinguishes itself from siblings like cards_find_transfer_programs_for_airline by explicitly mentioning multi-hop routing through hotel programs and live bonus application.

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 an explicit usage condition: 'Use when a card/program has no direct partner with the target.' This is clear and actionable, but it doesn't name alternatives or mention when this tool might be less appropriate (e.g., when direct partners exist but users want comparisons). It gives a strong trigger but lacks a full decision framework.

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=false (mutation) and destructiveHint=false. The description adds behavioral context beyond this: it mentions the email notification side effect, the authentication prerequisite, and the requirement that the flight already exists in the database. It does not cover edge cases like duplicate alerts or response structure, but the annotations cover the basic mutation safety profile.

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

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

The description is three concise sentences with no fluff. It front-loads the core purpose, then adds preference examples and a crucial prerequisite. 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 mutation tool with no output schema, the description covers the essential prerequisites (flight must exist, authentication required), the core behavior (email notification), and the supported preferences. It does not explain the response format or how to manage alerts (e.g., via fs_list_seat_alerts or fs_delete_seat_alert), but these are covered by sibling tools and the schema provides parameter details. Overall, it is complete enough for an agent to call 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 schema fully documents all six parameters. The description lists example preferences (window, aisle, exit row, specific seat, adjacent seats) which mirrors the enum values already in the schema. It does not add additional semantic meaning beyond the schema, 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?

The description explicitly states the verb (create) and resource (seat alert), and clarifies its function: notifying via email when a seat becomes available. It also distinguishes itself from sibling tools like fs_list_seat_alerts and fs_delete_seat_alert by focusing on creation, and references the prerequisite search_flight.

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 instructs when to use this tool vs alternatives: 'The flight must already be in our database — use search_flight first if not.' This is a clear directive for when this tool is appropriate and when another tool should be used first, and it also mentions the authentication requirement.

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 destructive and idempotent, so the 'delete' behavior is covered. The description adds a useful behavioral trait beyond the annotations: 'Requires authentication.' It does not contradict the annotations, and the destructive semantics align with destructiveHint=true.

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 primary action is front-loaded, and the follow-up guidance about finding the ID is directly relevant and necessary.

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

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

For a simple one-parameter delete tool with no output schema, the description covers the action, the required identifier, how to obtain that identifier, and the authentication requirement. Nothing essential for calling the 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% and the alert_id parameter is already described. The description adds value by telling the agent where to obtain the alert_id value through list_seat_alerts, which goes beyond the raw schema definition.

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

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

The description states a specific verb ('delete'), a specific resource ('seat alert'), and the key identifier ('by its ID'). This clearly distinguishes it from sibling tools like fs_create_seat_alert and fs_list_seat_alerts without requiring schema inspection.

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 tells the agent to use list_seat_alerts to find the alert ID, which is practical prerequisite guidance. It does not explicitly enumerate when not to use it or compare against alternatives, but the direction 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, so the agent knows this is a safe read operation. The description adds that it lists complementary remote MCPs, which is useful context. However, it doesn't disclose whether the tool returns installation instructions, URLs, or just names, nor does it mention any external network calls. With annotations covering the safety profile, a 3 is appropriate.

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 no waste. The first sentence states the action and resource, the second adds the scope of what will be listed. Information is front-loaded and 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 zero-parameter, read-only discovery tool with no output schema, the description is largely complete. It tells the agent what the tool does and what categories of MCPs will be listed. A minor gap is not specifying the output format (e.g., list of server names vs. installation commands), but given the tool's simplicity, this is not a significant omission.

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 description coverage is 100% (vacuously). The description doesn't need to explain parameters. Baseline 4 for zero-param tools is appropriate, and the description adds context about what the discovery covers.

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 purpose: discovering other flight & travel MCP servers to add to the client. It specifies the resource (MCP servers) and the action (discover/list). It distinguishes itself from the sibling 'lounge_discover_more_flight_tools' by mentioning complementary remote MCPs covering award flights, airport delays/wait times, and lounges, though it doesn't explicitly name the 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 implies when to use this tool: when the user wants to find additional flight/travel MCP servers to add to their client. It does not explicitly state when not to use it or name alternatives like lounge_discover_more_flight_tools. The context is clear but exclusions are absent.

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, open-world, and non-destructive, so the description need not restate safety traits. It adds useful output behavior—ranked list and interactive highlighted seatmap—but does not disclose ranking logic, availability semantics, or edge cases like conflicting preferences or no available seats.

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 concise sentences that front-load the core purpose and then state the return value. There is no filler or repetition beyond the mild overlap between 'best available seats' and 'recommended seats', which is acceptable.

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

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

With no output schema, the description correctly explains that the tool returns a ranked list and an interactive seatmap. However, it lacks detail on how preferences are weighted or combined, what happens when no seats match, and how this differs from the many sister fs_* seat tools, leaving moderate 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?

Schema description coverage is 100%, so the schema already documents flight_number, preferences, cabin_class, and flight_date. The description adds little beyond naming example preference values, which is redundant with the enum, 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 clearly states the tool finds the best available seats on a flight and matches user preferences, giving a specific verb and resource. It does not, however, distinguish itself from nearby siblings like fs_interactive_seat_finder or fs_get_seatmap, which could also serve seat-selection tasks.

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

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

The description implies this tool is the right choice when users have seat preferences such as window, aisle, or extra legroom, and when a ranked recommendation plus seatmap is desired. It does not explicitly say when to use an alternative like fs_interactive_seat_finder or fs_get_seat_reviews, nor does it provide exclusions.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds some behavioral context by listing the kind of data returned and noting that it also renders an interactive seatmap, which is beyond the annotations. However, it does not explain what 'renders' means in terms of output behavior, UI side effects, or return format.

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 primary purpose and data categories are front-loaded, and the secondary rendering behavior is in a short, separate sentence. Every phrase adds 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 read-only tool with only three simple parameters and complete schema coverage, the description is largely sufficient. It conveys the kind of information returned and the notable rendering side effect. The main missing piece is a clearer distinction from the seatmap-focused sibling tools, but the core invocation context is adequately covered.

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

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

Schema description coverage is 100%, with clear descriptions for flight_number, seat_number, and flight_date. The tool description adds no parameter-specific detail beyond what the schema already provides, so the baseline of 3 is appropriate. It does not explain edge-case formats or relationships between parameters 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 identifies a specific verb and resource: 'Get detailed information about a specific seat on a flight.' It also lists useful content dimensions like characteristics, cabin class, availability, and pricing. However, the additional claim 'Also renders the interactive seatmap' blurs the boundary with the sibling fs_get_seatmap, preventing a perfect sibling-distinguishing score.

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

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

There is no explicit guidance about when to choose this tool over related siblings such as fs_get_seatmap, fs_find_best_seats, or fs_get_seat_reviews. The phrase 'specific seat' implies a use case, but the separate seatmap-rendering claim actively creates ambiguity about which tool should be used for seatmap interactions. No exclusions or alternative routing are provided.

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, so the safety profile is established. The description adds valuable behavioral context by warning that data is cached, meaning the agent can expect potentially stale results and should use a different tool when freshness matters.

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 concise sentences each carry useful information: what the tool returns, what is included, and the cached-data caveat with an alternative. No filler or redundancy.

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

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

For a read-only retrieval tool with complete parameter schema and supporting annotations, the description covers purpose, return contents, presentation format, and data-freshness caveat. It provides enough for an agent to decide whether to call this tool or the alternative.

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 flight_number and flight_date are already well-documented in the schema. The description adds no further parameter-level detail, 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 clearly identifies a specific verb and resource: "Get the seat map for a flight." It further differentiates itself by listing the contents (all seats, cabin classes, characteristics, availability) and the visual format, distinguishing it from sibling tools like fs_get_seat_info.

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 warns that data is cached and directs the user to search_flight for fresh/updated data, providing a clear when-not and alternative. However, the named alternative "search_flight" does not exactly match the sibling tool name "fs_search_flight," creating minor ambiguity for an agent performing exact-name routing.

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 read-only nature is covered. The description adds valuable context by stating 'Free — no auth required' and listing the output fields, which goes beyond the annotations. It does not contradict annotations.

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

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

Two sentences with no filler. The first sentence states the core action and optional filter; the second lists output fields and the free/auth aspect. Information is front-loaded and 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 simple read-only tool with two parameters, one required, no output schema, and annotations covering the read-only and non-destructive nature, the description is complete. It specifies what data is returned, the optional filter, and the lack of auth requirement. 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?

Schema coverage is 100%, and both parameters ('flight_number' and 'seat_number') have clear descriptions in the schema. The description restates that the seat filter is optional but adds no additional syntax or details not already in the schema. Baseline of 3 is appropriate when the schema already documents parameters well.

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 clear resource ('user-submitted reviews for a flight'), and the optional filter by seat. It also enumerates the returned fields (ratings, comments, seat number, cabin, helpfulness votes), making its purpose unambiguous and distinct from sibling fs_* tools that handle seat maps or seat info.

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 about what the tool does and the optional seat filter, but it does not explicitly mention when to use this tool over alternatives like fs_get_seat_info or fs_find_best_seats. Since the name and description already convey the focus on reviews, the lack of explicit exclusions is a minor gap.

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 safety, so the bar for extra behavioral disclosure is lower. The description adds that the tool renders an interactive seatmap and recommends seats, which is useful, but it doesn't describe output format, how preferences are handled, or what 'best' means.

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

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

Two short sentences with zero filler. The core behavior is front-loaded immediately, and the usage context is stated in the second sentence without unnecessary 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 simple read-only tool with two parameters and no output schema, the description plus schema covers the essentials. It does not explain what an agent should expect in the rendered seatmap or whether recommendations are returned as data, but the tool is simple enough that this is a minor gap.

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

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

Schema description coverage is 100%, so both flight_number and flight_date are already documented in the schema. The description adds no additional parameter-level meaning, which is acceptable under the baseline.

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 specific verbs ('recommends', 'renders') and a clear resource ('best seats', 'interactive seatmap'), so an agent can tell what the tool does. It does not explicitly name the sibling tools it competes with, like fs_find_best_seats or fs_get_seatmap, which keeps it from a 5.

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

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

It gives a clear trigger: use this as the default when a user wants seat help but hasn't specified preferences. It does not state when to choose a different sibling tool for preference-specific seat searching or seatmap-only requests, so it lacks exclusions.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond the annotations: it lists active and inactive alerts, enumerates the displayed fields, and notes that authentication is required. This gives the agent meaningful expectations about invocation and output.

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 wasted words. It front-loads the primary action and scope, then provides useful output details and the authentication requirement. 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 list tool, the description is complete. It states what is listed, what output fields to expect, and the authentication precondition. No output schema is present, but the description compensates by enumerating the returned information.

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 is empty with zero parameters, so there is nothing the description needs to explain about parameters. Per the rubric, a zero-parameter tool receives a baseline of 4; no parameter information is missing.

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 a clear resource ('your seat alerts'), and explicitly includes both active and inactive alerts. This clearly distinguishes it from sibling tools like fs_create_seat_alert and fs_delete_seat_alert.

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

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

The description implies when to use the tool: when you want to view your existing seat alerts and their details. However, it does not explicitly state when to prefer this over related tools or mention alternatives, so usage guidance is only implied, not stated.

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?

Discloses meaningful behavior beyond the annotations: requires a signed-in account, consumes a search credit, has a paid-plan restriction, and returns an interactive seatmap. The annotations only indicate non-readOnly and open-world behavior; the description adds the auth, cost, and data-freshness 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?

Four sentences with no filler. The first sentence front-loads the core purpose, and each subsequent sentence contributes distinct, actionable information: auth, paid-plan behavior, credit cost, and return type.

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 sufficient for a competent agent to invoke the tool: it covers prerequisites, cost, plan limitations, and the output type. With no output schema present, the mention of an interactive seatmap helps, though explicit routing among sibling flight-search tools would improve completeness.

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% for both parameters, with flight_number and flight_date already described inline. The description does not add parameter-specific meaning beyond the schema, 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?

The description states a specific action — search for a flight and return fresh seatmap data — plus an output type. It is clear about the resource involved, but it does not explicitly distinguish itself from sibling tools like lookup_flight or fs_get_seatmap.

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 useful context: OAuth sign-in is required, paid plan users can search flights not yet in the database, and each search costs a credit. However, it never states when to choose this over alternatives or when not to use it, leaving the routing decision 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it accepts a slug OR a loose name, returns editorial Q&A that can be cited directly, and is free/no account needed. These are operational traits an agent needs to know. It doesn't disclose pagination or response size, but for a single-parameter lookup tool this is minor.

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: what the tool returns, when to use it, and key operational facts (loose name accepted, citable, free). The most important scoping information is front-loaded. No 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?

For a simple one-parameter read-only lookup with no output schema, the description covers the essential context: what it returns, how to invoke it, and what the agent can do with the result. It doesn't describe the response structure, but since there is no output schema and the tool is a free-form editorial Q&A, the absence is acceptable. It could mention that results are programme-specific and may not cover all programmes, but the examples already imply this.

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 the 'program' parameter with examples. The description adds meaning by clarifying that the parameter accepts both a slug and a loose name, and by listing example values that overlap with the schema. This is a small but real addition beyond the schema, so slightly above 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 states a specific verb ('Get'), a clear resource ('curated award-chart FAQs, sweet spots, and booking tips'), and a target domain ('loyalty programme'). It also names example programmes, which distinguishes it from generic knowledge-base tools like search_knowledge_base and from award-chart data tools like get_program_partner_chart. The purpose 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 explicitly says 'Use to answer questions about a programme's award pricing, best redemptions, and how to book,' which gives clear context for when to invoke it. It does not explicitly name alternatives or exclusions, but the sibling list contains related tools (get_program_partner_chart, get_partner_award_options, recommend_redemption) that an agent could confuse it with; the description's focus on editorial Q&A and booking tips provides enough differentiation. A small gap: no explicit 'use X instead' 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 indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by explaining that the tool returns the release window in days from departure and connects this to inventory loading at 330 days, which helps set expectations about the data returned.

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

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

The description is concise and front-loaded: the first clause states what the tool does, and the second sentence gives actionable usage context. There is no redundant or filler language.

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 single-parameter read-only lookup with no output schema, the description covers what the tool returns, why it matters, and when to invoke it. Nothing essential is missing for an agent to select and use 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%, with the single 'airline' parameter already described as IATA code or carrier name. The description does not add further parameter-level detail, and the baseline of 3 applies because the schema carries the parameter documentation burden.

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 action ('Look up when an airline opens award seats for booking') and identifies the resource (airline award release window). It is distinct in meaning from the sibling list_award_release_windows, though it does not explicitly name or contrast itself with that alternative.

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 on when to use this tool: before searching for a date more than 330 days out, to warn the user about unloaded inventory and suggest a retry date or route monitor. It does not discuss when not to use it or alternatives, but the use case is clearly 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 declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds value by disclosing the account requirement and the nature of the response (direct booking links). No contradictions 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?

Two concise sentences front-load the core purpose and immediately list the returned fields, then give the required input and prerequisite. No filler or redundant phrasing.

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 single-parameter read-only tool, the description covers the input source, output content, and access requirement. Since there's no output schema, the description sufficiently explains what the caller can expect. 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 schema already describes trip_id as 'The trip_id field from an award search result row'. The description reinforces this by explaining where to obtain it, adding context about the source (seats.aero) and that it comes from a specific search result. This enriches the schema's minimal description.

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

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

The description states a specific verb ('Get') and resource ('flight-level detail for one award result'), enumerates the exact fields returned (flight numbers, aircraft, times, stops, booking links), and names the source tools (search_all_airlines or search_availability). This clearly distinguishes it from the many sibling search 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 provides a clear usage instruction: pass the trip_id from a seats.aero result row. It also states a prerequisite (connected seats.aero account). While it doesn't explicitly say when NOT to use it (e.g., for cash flights), the context makes the intended use obvious.

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 cover read-only and non-destructive behavior. The description adds meaningful extras: 'Free — no account needed' (auth requirement), the return composition (tiered base purchase pricing and active bonus promotion), and the behavior when program is omitted. These go beyond the annotation baseline.

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 fluff: purpose is front-loaded, followed by return details, then usage/optional/auth info. Each sentence earns its place, though the use case sentence slightly overlaps with the first sentence in meaning.

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

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

For a read-only tool with 2 optional parameters, no output schema, and existing safety annotations, this description covers purpose, return content, optional parameter behavior, and auth. It doesn't detail the response structure or explicitly differentiate from overlapping pricing siblings, but is largely sufficient.

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

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

Schema coverage is 100% and both parameters already have clear descriptions. The description's use case example ('how much does it cost to buy X') reinforces the quantity meaning but does not add new information 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 states a specific verb+resource: 'Get the cost to buy points/miles for a loyalty program.' It also describes the return content (tiered base purchase pricing, active bonus promotion) and gives the exact question it answers, clearly distinguishing it from generic pricing siblings like get_pricing or get_program_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?

It explicitly says 'Use to answer "how much does it cost to buy X Avios/miles/points?"' which provides a clear when-to-use context. However, it does not name alternative tools (e.g., get_pricing, get_program_rates) or state when not to use it, so it stops short of full disambiguation.

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

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

The annotations already indicate read-only, non-destructive, and open-world behaviour. The description adds useful context beyond that: the operation is free and requires no account, returns a source link, and clarifies the own-vs-partner programme scope. It does not discuss idempotency despite idempotentHint=false, but the added operational context is meaningful.

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

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

Three tight sentences, front-loaded with the core purpose, followed by output summary, input flexibility, and an important scoping caveat. Every sentence earns its place with no fluff or redundancy.

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

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

For a single-parameter, read-only tool with no output schema, the description provides a complete picture: what it does, what it returns, what input forms are accepted, the key edge case (partner programmes), and access requirements (free, no account). 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?

Schema coverage is 100% and the schema documents the airline parameter as 'slug or name' with examples. The description adds the nuance 'acceptable slug or a loose airline name', clarifying that exact slugs are not required. This goes slightly beyond the schema by indicating tolerance for loose input.

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 the award-ticket cancellation/redeposit fee for an airline's OWN loyalty programme.' It also states what is returned (headline fee, exemptions, source link), and explicitly distinguishes this from partner-programme fees, making it easy to differentiate from sibling tools like get_partner_award_options.

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

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

It clearly establishes when to use the tool (for an airline's own loyalty programme) and includes an explicit when-not: fees for booking through a PARTNER programme differ, and this tool returns the airline's direct policy. However, it does not name a specific alternative tool to use for partner-programme fees, so it lacks a fully explicit alternative.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description is consistent with those. The description adds the non-obvious 'Free' cost signal and clarifies that the result is a table of percentages per booking class, which goes 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?

Three sentences with no filler. The core action and result are front-loaded, the use case is stated next, and the cost/access note ('Free') is kept to a single word.

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 read-only lookup with complete schema descriptions and safety annotations, the description covers purpose, output shape, and when to use it. There is no output schema, but the description sufficiently explains the return value, and edge cases like omitted fare_class are handled in the parameter schema.

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%, with clear descriptions for airline, program, and fare_class, including the optional behavior of returning the full table when fare_class is omitted. The description adds some contextual framing around booking class and crediting, but does not materially supplement the schema's parameter documentation.

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

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

The description uses a specific verb ('Look up') and names the exact resource ('mileage earning rates for crediting a partner-airline ticket to a loyalty program'). It also states the output shape ('% of distance earned per booking class'), which clearly differentiates it from vague or tautological tool descriptions.

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 when deciding which program to credit a flight to,' giving a clear decision context. However, it does not name alternatives such as calculate_flight_earnings or get_program_rates, nor does it state when not to use the 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that. It adds the scope that redemptions are included, but does not disclose error behavior, authorization, or response format.

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

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

A single, front-loaded sentence that contains no filler and communicates the operation and resource 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?

For a one-parameter read-only lookup with annotations covering the safety profile, the description is mostly sufficient. It could specify what 'details' includes or behavior for missing IDs, but the core call shape is clear.

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 has 0% description coverage for booking_id, and the description does not explicitly define it or explain where to obtain it. It only weakly ties the ID to 'specific flight booking', which is not enough compensation.

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 ('Get') and specific resource ('flight booking/redemption'), and the word 'specific' distinguishes it from list_flight_bookings while 'flight' distinguishes it from get_hotel_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?

No guidance on when to use this tool versus list_flight_bookings or how it fits with add/update/delete variants. There are no explicit alternatives, prerequisites, or exclusion criteria.

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

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

The annotations already cover read-only and non-destructive behavior, so the description does not need to repeat that. It adds a meaningful extra behavioral trait by flagging 'Paid feature' and implies live/open-world data with the word 'current'. 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?

Two sentences with no filler. The primary action is front-loaded, and the second sentence adds high-value workflow and cost 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?

The description is minimally viable: it names the inputs conceptually and gives workflow guidance, but with no output schema and low parameter coverage it does not explain what the invocation returns or how the date range maps to availability. An agent could call it, but would still have meaningful unknowns.

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 only 33%, and the description does not compensate. It mentions a 'hotel' and 'specific dates' but adds no meaningful detail about check_in_date/check_out_date semantics, date format, or whether availability is per-night or for the whole stay.

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 clear verb ('Get') and resource ('current points availability for a hotel'), with date scoping. It also explicitly distinguishes itself from monitor_hotel_price by saying 'Use BEFORE monitor_hotel_price', which helps an agent know what this tool is and is not.

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

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

Explicitly tells the agent when to use this tool: before monitor_hotel_price, to find the correct rate_plan and current points rate. It lacks exclusions or broader alternative guidance, 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, so the safety profile is covered. The description adds the useful detail that the tool returns both details and full price history, but it does not disclose behavior around monitoring status, response format, or potential errors. 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?

A single, efficient sentence front-loads the core behavior: 'Get details and full price history of a monitored hotel booking.' There is no filler or repetition, and it contains the essential information for an agent.

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 one simple integer parameter, read-only annotations, and no output schema, the description is mostly adequate. However, it does not clarify what 'monitored' means in relation to sibling tools like monitor_hotel_price, nor what 'details' includes. An agent may be uncertain about the exact scope and return value.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining the parameter. The description does not mention booking_id at all, though the parameter's name and the tool's name make its purpose inferable. This is minimal compensation but not enough given the lack of schema documentation.

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 the specific verb 'Get' with the resource 'hotel booking' and elaborates with 'details and full price history', clearly distinguishing it from siblings like list_hotel_bookings, get_flight_booking, and monitor_hotel_price. An agent can immediately understand what this tool does and how it differs.

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 'monitored hotel booking' implies that this tool is for bookings that are being price-monitored, giving some usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or how to obtain the booking_id.

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 valuable behavioral context beyond that: results are 'off-peak/saver estimates from published partner award charts' and the tool is 'Free — no account needed'. This gives an agent a realistic sense of data quality and access requirements.

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 main function, followed by a concrete example, a practical use case, and two concise caveats. Every sentence earns its place without redundancy or unnecessary elaboration.

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 lookup with three clearly documented parameters, the description adequately covers inputs, outputs (loyalty programmes and point costs per cabin), and important caveats. With no output schema present, the description gives enough shape of the return value; a minor gap is not specifying how results are ordered or whether empty results are possible.

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%, with all three parameters (carrier, departure, destination) already documented with IATA codes and examples. The description repeats some of that context but does not materially add parameter semantics beyond what the schema already provides, 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?

States a specific action and resource: given an operating airline and route, list loyalty programmes that can book it as a partner and show point costs per cabin. The included Korean Air/ICN-LAX example clarifies the exact input/output relationship, and the inverse framing (airline-to-programs, not program-to-airlines) distinguishes it from siblings like get_program_partner_chart.

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 a concrete use case: 'Use this to answer "which of my programmes can book this flight and what's the cheapest?"'. This gives clear guidance on when to invoke the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already specify readOnlyHint=true, destructiveHint=false, so the tool is clearly safe and read-only. The description adds valuable behavioral context by explaining the 'best way to use the currency' and the flexible input handling, which is not in the schema or annotations. It also discloses that observed values may be included with a sample size, which is extra transparency beyond the structured data.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then provides output details and usage examples. It is efficient with no wasted words, though slightly dense. The free usage note at the end is useful context, but could be omitted without loss, so not a 5.

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 simplicity of the tool (one parameter, no output schema), the description covers the essential aspects: what it returns, how to call it, and its read-only nature via annotations. The observed-value detail adds depth. The only minor gap is that it doesn't specify error conditions for unrecognized currencies, but this is not critical for a lookup tool.

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

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

Although schema description coverage is 100%, the description enriches the single 'currency' parameter by providing examples (chase-ultimate-rewards, 'amex points') and clarifying that it accepts both slugs and loose names. This interpretation guidance goes beyond the schema's simple type description, helping the agent format the query correctly.

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: retrieving cents-per-point valuation for points/miles currencies and hotel programs. It goes beyond a simple verb+resource by including the specific output (headline valuation, observed value, best use) and examples, which makes its purpose unmistakable. It also distinguishes itself from related sibling tools like get_buy_points_pricing, get_earning_rates, and get_program_rates by focusing on valuation rather than pricing or earning 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 provides implicit usage context by indicating that it answers valuation questions and accepts flexible inputs (slug or loose name). It does not explicitly name alternative tools or provide 'when not to use' guidance, but the examples and stated free access imply it's for quick valuation lookups. This is clear enough for an agent to decide when to invoke it, though not as explicit as naming 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?

Annotations already cover readOnlyHint and destructiveHint, so the description adds value by noting the snapshot dependency and the signed-in user requirement. It also implies a refresh semantics without contradicting annotations.

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

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

Two well-structured sentences with no filler. The first sentence lists what the tool returns, the second provides a clear usage directive. Perfectly front-loaded and efficient.

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

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

Without an output schema, the description sufficiently enumerates the returned data categories and the refresh trigger. It covers the essential context (signed-in users, snapshot source) for an agent to decide when to call it, though it could briefly mention that it's a read-only aggregate view (already covered by annotations).

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 schema is trivially complete (100% coverage). The description doesn't need to explain parameters; it appropriately focuses on output content and usage 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 retrieves a comprehensive travel rewards portfolio summary, listing specific content categories (points, spend, trips, trends). It distinguishes from granular get_* siblings by emphasizing the aggregate 'portfolio' scope, though it doesn't name any sibling explicitly.

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

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

Provides explicit when-to-use guidance: 'call after the user adds bookings or balances in-session when you need a refresh.' This gives a clear trigger condition, though it doesn't mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to state safety. The description adds useful context: the response is points per cabin class with off-peak/peak, and that it's a paid feature. However, it doesn't disclose what happens if the route isn't supported or if the user doesn't have a paid plan, which could be relevant.

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 sentences, each adding a distinct piece of information: the core purpose, what it shows, and the note about paid feature. It's front-loaded with the main action. 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?

For a simple read-only tool with clear parameters from schema, the description covers the basics. However, the lack of output schema means the description should hint at the return structure more explicitly, which it partially does (points per cabin class, off-peak/peak). But it doesn't mention edge cases like unsupported routes or error handling, which might be important for a paid feature.

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

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

Schema description coverage is 0%, so the description must compensate. The description names the route parameters (airline, departure_code, arrival_code) implicitly by saying 'airline route', but it doesn't explain the airline enum values, the format of the codes (though pattern is in schema), or any nuances. It adds minimal value beyond the schema's field names.

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 it gets an award pricing chart for a specific airline route, showing points per cabin class with off-peak/peak distinction. It distinguishes from many pricing-related siblings like 'get_buy_points_pricing' or 'get_program_rates' by focusing on route-specific award charts, though it doesn't explicitly name an alternative.

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 says 'No date needed' and 'Paid feature', which gives some guidance on when to use it. However, it doesn't explicitly say when not to use this vs alternatives like 'search_availability' or 'get_partner_award_options', and doesn't mention any prerequisites like having a paid subscription.

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 and openWorldHint annotations, the description adds important behavioral caveats: points are one-way unless trip_basis says round_trip, ANA is round-trip, charts apply only to partner-operated flights, and results include confidence/caveats fields. It also says it's free and needs no account, which is useful non-obvious 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 description is compact but information-dense: core purpose first, then supported programmes, then a clear 'how to read' instruction, then critical caveats. No sentence is redundant, and the structure front-loads the most important 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?

With only one parameter and no output schema, the description carries the burden of explaining the returned data, and it does so thoroughly: table type, supported programmes, how to interpret rows, key fields to check, and the partner-only limitation. Nothing essential for using 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?

The schema already fully documents the single 'program' parameter with an enum and description. The description adds value by noting that cathay-asia-miles is distance-basedhare and by listing the supported values inline. This goes slightly beyond the schema's basic enum, so a 4 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: 'Get a loyalty programme's PARTNER airline award chart', and then precisely defines the output form ('region-pair or distance-band table'). It also distinguishes the scope from the programme's own dynamically-priced flights, which helps an agent separate this from other pricing/award 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 clear contextual guidance: it lists the supported programmes, tells the agent to match route regions/distance to a row, and instructs the agent to read specific returned fields. It does not explicitly name alternatives or state when not to use this tool versus siblings, but the context and supported-list make the intended usage 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 mark the tool as readOnly and non-destructive, and the description reinforces that this is a safe read operation. It adds helpful context beyond annotations by stating no account is needed and describing the detailed return data. It does not mention rate limits or data freshness, but it is adequate for this simple read-only tool.

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

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

The description is three short sentences with no filler. It front-loads the core action and resource, then adds the return details and access note. Every sentence contributes useful 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?

With only one required enum parameter and no output schema, the description provides enough context to invoke the tool and interpret its results: full award chart rates, destinations, cabin classes, and off-peak/peak pricing. Access prerequisites are addressed with 'Free — no account needed.' Nothing essential is missing for this simple lookup.

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 property description already providing examples and an enum of allowed values. The tool description adds no new parameter-level meaning beyond 'specific loyalty program.' Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly states the verb and resource: 'Get the full award chart rates for a specific loyalty program.' It also specifies the return scope: all destinations, points per cabin class, and off-peak/peak pricing. It does not explicitly name a sibling to distinguish itself from, but the resource is specific enough.

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 makes it clear when to use this tool: when the full award chart for a loyalty program is needed. It adds the access context 'Free — no account needed,' which helps agents choose this over authenticated operations. It does not mention alternatives or exclusions, but this is a simple one-parameter lookup.

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