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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds useful behavioral context beyond that: the server only acts when bookingId and email match the booking, which is a verification/authorization trait not visible in structured fields. It stops short of describing refund timing, reversibility, or failure modes.

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 paragraphs, the action and the mandatory pre-step front-loaded, with zero filler. Every sentence carries either the operation or a constraint.

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 mutation with no output schema, the description covers the precondition, the credential-matching rule, and the sibling to consult first. It leaves the post-cancellation result (confirmation, refund mechanism) to be inferred, which 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 required parameters and the optional lastName are already documented in the schema. The description restates the email-matching rule but adds no syntax, format, or ID-source detail beyond what the schema provides. Baseline 3 is correct here.

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

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

States a specific verb and resource ('Cancel a confirmed tour or activity booking') and names the exact sibling it must not be confused with implicitly via the tour/activity scope, versus cancel_hotel_booking. An agent can route correctly without opening either schema.

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

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

Gives an explicit precondition and sequencing rule: first show the refund from getExperienceBookingCancelPreview and wait for a clear yes. It also states the matching requirement for bookingId and email, so the agent knows both when to use this tool and what must be true before calling 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 destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: it discloses the financial consequence (a non-refundable booking or one past its free-cancellation deadline can be charged in full) and the auth rule (server only acts when bookingId and email match). It stops short of describing the post-cancellation response/confirmation state, which keeps it from a 5.

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

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

Two sentences, no wasted words, with the prep step and consequence front-loaded before the credential requirement. The second sentence mildly repeats the schema's auth rule, which is the only 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 destructive mutation with no output schema, the description covers the prerequisite lookup, the customer-confirmation requirement, the penalty risk, and the credential matching rule. The main omission is any statement of what a successful cancellation returns or how failures surface, but that is minor given the richness elsewhere.

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 bookingId, email, and the optional lastName including the matching check. The description restates the bookingId/email requirement but adds no new syntax, format, or fallback guidance, 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?

States a specific verb+resource ('Cancel a confirmed hotel booking') and implicitly distinguishes itself from the sibling cancelExperienceBooking, which cancels a different resource type. An agent can select this over the other cancel tool without opening the schema.

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

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

Gives an explicit prerequisite workflow ('First check the cancellation policy with `get_bookings_bookingid` and confirm with the customer') and names the sibling tool to use beforehand. It also states the condition under which cancellation carries a penalty, which is the key decision context for invoking this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally; the description adds the non-obvious authorization behavior — the server only returns or changes a booking when bookingId and email match. It does not mention rate limits or error behavior when the pair does not match, so it falls short of a 5.

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

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

Two tight sentences with the resource and payload front-loaded ahead of the access condition. The second sentence slightly restates the email-verification note already present in the schema, which is a minor 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?

With no output schema, the description compensates by enumerating the returned fields (status, hotel, dates, rooms, guests, price, cancellation policy) and states the credential requirement. An agent has everything needed 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 description coverage is 100%, so the schema already explains bookingId, email and the optional lastName; the description only restates the two required parameters. It adds no format, matching or fallback detail beyond what the schema carries, 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?

States a specific verb+resource ('Look up a confirmed hotel booking') and enumerates the payload (status, hotel, dates, rooms, guests, price, cancellation policy), which cleanly separates it from get_flights_bookings_bookingid and getExperienceBooking. An agent can pick it out of a large sibling list without opening the schema.

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

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

The description states the precondition for use (the booking must exist as a confirmed booking and both bookingId and email must match) but never names an alternative tool or when to prefer a sibling such as cancel_hotel_booking or put_bookings_bookingid_amend. Context is clear, 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by stating 'No parameters required' and enumerating the returned fields (chain list, numeric IDs, names), which matters since there is no output schema.

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

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

Front-loaded with the answer in the Overview, and the four header sections are easy to scan. It slightly over-structures a trivial 0-param lookup and repeats the 'use chain IDs in search filters' point in both Overview and Quick Start, which is mild redundancy rather than waste.

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

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

For a zero-parameter reference-data tool with no output schema, the description covers what it returns, that it needs no input, and how the result is consumed. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description reinforces this ('No parameters required. Returns all hotel chains with IDs'), leaving no ambiguity about invocation.

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 Overview states a specific verb and resource ('Get all available hotel chains'), gives concrete examples (Marriott, Hilton, IHG), and names the downstream purpose ('Use chain IDs to filter hotel searches by brand'). This clearly separates it from sibling reference-data tools like get_data_cities, get_data_hoteltypes, and get_data_hotels.

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

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

The 'When to Use' section gives three concrete scenarios (chain filters, brand selection, reference data), which is good context. However, it doesn't contrast with the nearest siblings such as get_data_hoteltypes or explain when you'd want chains versus other hotel reference data, so it stops short of 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that the call returns the complete, unpaginated city list and requires an ISO-2 code, but says nothing about error behavior for invalid codes or response size limits.

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 four-section markdown document with redundant bullets ('city dropdowns', 'location filters', 'autocomplete' all describe the same one-line lookup) is disproportionate for a single-parameter read tool. The front-loaded overview is good, but most of the structure is boilerplate rather than 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 trivial lookup with 100% schema coverage, present annotations and no output schema, the description supplies what an agent needs: the input format, the prerequisite endpoint, and the shape of the result. Only failure-mode and volume details are missing.

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

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

Schema coverage is 100%, so both parameters (countryCode, timeout) are already documented with the ISO-2 format and an example. The description restates the same format requirement without adding syntax or edge-case detail, 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?

States a specific verb and resource ('Get a list of all cities within a specific country') and bounds the scope to a single country, which distinguishes it from siblings such as get_data_countries and get_data_hotels. An agent can identify the operation without opening the schema.

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

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

The 'When to Use' section gives concrete contexts (dropdowns, location filters, autocomplete) and the Quick Start supplies the prerequisite chain: obtain the ISO-2 code from the country-list endpoint first. It lacks explicit when-not guidance, but the intended usage is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered without the description's help. The description adds that no parameters are required and enumerates the returned fields, but says nothing about caching, rate limits, pagination, or ordering of the list.

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 parameter-free reference lookup is expanded into six markdown sections with redundant bullets and marketing filler ('Essential for building country selection interfaces', 'Populate country selection lists'). The 'What You Get' and 'Quick Start' sections largely repeat the Overview.

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 trivial, output-schema-less list endpoint, the description does supply the return content (country names and ISO-2 codes) that an agent would otherwise lack. It is more than sufficient to call the tool correctly, though the return format specifics remain implicit.

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

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

Schema description coverage is 100%, so the single 'timeout' parameter is already fully documented by the schema; the description correctly notes 'No parameters required' but adds no information beyond that. Baseline 3 per the rubric.

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

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

States a specific resource ('complete list of all countries') and the payload detail that distinguishes it ('with their ISO-2 country codes'). An agent can tell this apart from get_data_cities, get_data_languages, and get_data_currencies purely from the description.

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 'When to Use' section gives four concrete scenarios (dropdowns, location filters, form inputs, reference data for other endpoints). It gives clear context for calling it but never names an alternative tool or says when NOT to use it, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds useful context on the return content and explicitly notes no parameters are required to retrieve the full set, which helps the agent understand the call is a full-dump read.

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?

Markdown headings front-load the purpose well, but the content is repetitive: the opening paragraph, 'What You Get', and 'Quick Start' restate the same currency codes/names/country mapping three times. For a simple zero-input list tool this is oversized.

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 reference-data endpoint with no output schema, the description adequately covers what is returned. The only gap is that it never hints at result size or pagination, which matters for an open-world 'return all' call.

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

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

There is one parameter (timeout) with 100% schema description coverage, so the schema already does the work. The description's 'No parameters required' is accurate since timeout is optional infrastructure, but it adds no syntax or 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?

The description names a specific verb and resource ('Get all available currencies'), and states the exact payload (codes, names, country mappings). It is clearly distinguishable from siblings like get_data_countries or get_data_cities that deal with other reference data.

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 'When to Use' section gives concrete contexts (dropdowns, price display, conversion, booking endpoints), which is more than implied usage. It stops short of naming alternatives or when-not-to-use conditions, so it is not 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered and the bar is lower. The description usefully adds that no parameters are required and that the full facility set (not a filtered subset) is returned, though it says nothing about pagination, caching, or data freshness.

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 markdown structure is front-loaded and readable, but there is real redundancy: 'Multi-language names' and 'Translations' are the same bullet twice, and the Overview and Quick Start both restate that facility IDs are used in hotel search filters. Roughly a third of the text repeats itself.

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 reference-data endpoint with complete annotations and no output schema, the description tells the agent everything needed: it needs no arguments, returns the whole facility list with IDs and localized names, and the IDs plug into hotel search filters. No material gap remains.

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

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

The tool takes zero parameters, so the baseline is 4. The description confirms 'No parameters required,' which is consistent with the empty schema and closes the loop for the agent rather than leaving it to inspect 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 states a specific verb and resource ('Get all available hotel facilities (amenities) with multi-language translations') and frames the output's purpose (facility IDs for search filters). This clearly distinguishes it from siblings like get_data_hoteltypes or get_data_languages, which cover different reference data.

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 'When to Use' section gives four concrete scenarios (facility filters, facility display, multi-language support, reference data), which is strong context. However, it never names an alternative tool or a when-not condition, so the agent must infer the boundary with sibling reference-data endpoints on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the default behavior ('call with no parameters to get all airlines') and enumerating the returned fields (name, IATA/ICAO codes, country, alliance, logo URL), which helps the agent predict results.

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

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

It is front-loaded with an Overview and scannable headers, which aids selection. But the 'What You Get' bullets are padded and repetitive ('Full airline records including...', then 'Alliance membership for each airline', then 'Active status...'), restating content already implied by the parameter list and title.

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 must carry the return-value burden, and 'What You Get' does describe the fields returned. Combined with full schema parameter coverage, an agent has enough to call the tool correctly; only sibling disambiguation is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented, making 3 the baseline. The description reinforces the parameters with the Quick Start ('q' searches by name, 'activeOnly=true' excludes inactive) and expands the alliance names, but omits 'vanilla_alliance' and adds no syntax or format detail the schema lacks.

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 Overview states a specific verb and resource: 'Retrieve a list of airlines with optional filtering by name, alliance, and active status.' An agent immediately knows the operation. However, it does not distinguish itself from closely named siblings like get_data_flights_airlines_iatas or get_data_flights_airlines_iatas_iatacode, which is the exact ambiguity an agent faces here.

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 'When to Use' section gives three concrete scenarios (directory building, alliance filtering, active-only retrieval), which is clear context for invoking it. It stops short of a 5 because it names no alternatives or exclusions, even though siblings like the IATA-list tools exist and could be confused with this one.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuine value beyond that by describing the return payload (IATA codes paired with names) even though no output schema exists, plus the activeOnly filter behavior. No pagination or result-size caveats, though.

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

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

Front-loaded with an Overview, which is good, but for a one-parameter lookup tool the four markdown sections are heavy and the 'Quick Start' paragraph largely restates what Overview and When to Use already said. Adequate but not tight.

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 trivial one-optional-parameter read tool with annotations and no output schema, the description covers when to use it, what comes back, and how the filter behaves. The only omission is any hint of list size or ordering limits, which is minor.

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 activeOnly parameter is already documented, so baseline is 3. The description adds useful context by framing it as 'Active filtering available' with the effect of filtering out inactive airlines, slightly above 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?

States a specific verb+resource: 'Retrieve a lightweight list of airline IATA codes with names.' The word 'lightweight' implicitly separates it from the fuller sibling get_data_flights_airlines, but it never names the alternatives (get_data_flights_airlines, get_data_flights_airlines_iatas_iatacode), so the agent must infer the distinction.

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 'When to Use' section gives three concrete scenarios (autocomplete, client-side filtering, code validation), which is clear positive guidance. It stops short of stating when NOT to use it or which sibling to pick for a single-code lookup, so it does not reach 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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered externally. The description adds real value beyond that by enumerating what is returned (name, codes, country, alliance, logo URL, active status), which matters because no output schema exists. It does not mention error behavior for invalid or unknown codes.

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

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

Content is front-loaded and each section is coherent, but four markdown headings are disproportionate for a single-parameter read lookup. Some phrasing ('Fetch airline details to display alongside search results') restates the same idea already given in the overview.

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 tool with no output schema, the description covers the gap well by describing return fields, the alliance enum, active status, and a usage example. An agent has everything needed to call it correctly and interpret the response.

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 single parameter is already documented as '2-letter IATA airline code (e.g., AA)'. The description's Quick Start repeats that same example without adding format constraints or edge-case behavior, so the schema does the heavy lifting. Baseline 3 applies.

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

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

States a specific verb (Retrieve), resource (full details for a specific airline), and lookup key (2-letter IATA code). This clearly distinguishes it from sibling list tools like get_data_flights_airlines and get_data_flights_airlines_iatas, which return collections rather than a single record.

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 'When to Use' section gives three concrete scenarios (display, enrichment, validation), which is strong context. However, it never names the alternative list tools or states when NOT to use this (e.g., 'to list all airlines, use get_data_flights_airlines'), so routing between siblings is left 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the 2-character minimum and relevance-ranked result ordering, which is genuinely useful context, but says nothing about error behavior, rate limits, or empty-result handling.

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

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

Front-loaded and well organized, but heavily over-structured for a one-parameter search tool: four markdown sections repeat the same two facts (query by name/city/code, minimum 2 characters) across Overview, What You Get, and Quick Start.

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 'What You Get' section compensates by enumerating returned fields (matching airports, IATA codes, city/country, coordinates) and their downstream use. Combined with full annotation coverage, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100% for the single parameter, so the schema already documents the minimum length and example values. The description's 'q query string (minimum 2 characters)' largely restates the schema rather than extending it with matching syntax or relevance-tuning hints.

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 Overview states a specific verb and resource: 'Search for airports by name, city, or IATA code using a text query.' This is clear and unambiguous. It does not, however, distinguish itself from look-alike siblings such as get_data_flights_airports_iatas or get_data_iatacodes, which an agent could easily 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?

The 'When to Use' section gives three concrete scenarios (autocomplete, discovery, search validation) and ties the output to a downstream tool (post_flights_rates). It never states when NOT to use it or names an alternative sibling for full-list needs, so it falls short of explicit 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds behavior annotations don't: it is a bulk 'lightweight' list intended for download-once-and-filter-locally usage, and it enumerates the returned fields in the absence of an output schema.

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

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

Headers make it scannable and the purpose is front-loaded, but for a single-optional-filter tool the content is padded and self-repeating: the 'Quick Start' paragraph restates what 'When to Use' and 'What You Get' already said about calling with and without q.

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 compensates by listing returned fields (IATA codes, names), which is the right move. It is undermined by the required-vs-optional contradiction for q and by no mention of result size or pagination behavior for a bulk list tool.

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

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

Schema coverage is 100% but that coverage is only the string 'Search query', so the description meaningfully clarifies that q filters by name or by code. However, it also claims 'Call with no parameters to get all airport codes and names' while the schema marks q as required, which is an unresolved conflict in parameter semantics rather than added clarity.

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: retrieve a lightweight list of airport IATA codes with names. It differentiates the payload (codes + names, optional filtering) from the broader get_data_flights_airports sibling, though it never explicitly contrasts with get_data_iatacodes or get_data_flights_airlines_iatas.

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 'When to Use' section gives three concrete scenarios (autocomplete, client-side filtering, code validation), which is clear context an agent can match against. It stops short of naming the alternative siblings (e.g., the per-code lookup tool) or stating when not to use this one.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context via 'What You Get' — enumerating returned fields (name, city, country, timezone, IATA/ICAO, coordinates) since no output schema exists. It does not describe error behavior for an invalid or unknown code, keeping it below 5.

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

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

Markdown sections are front-loaded with the purpose first, and the heading structure makes scanning easy. There is mild redundancy between 'When to Use' and 'What You Get' plus a somewhat ceremonial 'Quick Start' for a one-parameter tool, but nothing seriously wasteful.

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 endpoint with no output schema, the description supplies the return-field inventory and usage contexts an agent needs to select and call it correctly. Nothing material 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 there is a single required parameter already documented as '3-letter IATA airport code (e.g., JFK)'. The description repeats the same example and format with no additional syntax, casing, or validation detail, 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?

States a specific verb and resource: retrieve detailed information for a specific airport by 3-letter IATA code. The singular-lookup framing distinguishes it from siblings like get_data_flights_airports and get_data_flights_airports_iatas, which are list-style endpoints.

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 'When to Use' section gives three concrete scenarios (airport display, flight result enrichment, autocomplete validation) that tell an agent when this is the right call. It does not explicitly name the alternative tool to use for a full airport list, 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful return-shape context (what fields come back) but says nothing about rate limits, error conditions, or behavior when hotelId is invalid/unknown. With annotations carrying the safety load, this is adequate but not rich.

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

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

It is heavily padded with Markdown headers and bullet lists that restate the same idea four times ('What You Get' re-lists what the Overview already named; the four 'When to Use' bullets are near-duplicates). Front-loading is fine, but a large share of the text does not earn 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?

There is no output schema, and the description does a reasonable job enumerating the returned fields, which is the main thing an agent needs here. Still missing is any differentiation from the crowded hotel-sibling set, which is the key context gap for this 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?

Schema description coverage is 100%, so the schema already documents hotelId, timeout, language, and advancedAccessibilityOnly. The description only reaffirms that hotelId is required and passed as a query parameter; it adds no format, default, or interaction detail (e.g., what advancedAccessibilityOnly changes) 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 overview states a specific verb+resource: fetch comprehensive details for a specific hotel (description, amenities, images, location, ratings). That is clear enough to act on. However, it never distinguishes itself from the many hotel siblings (get_data_hotels, get_data_hotel_search, get_data_hotel_ask, get_data_hotels_room_search), so an agent cannot tell which one to pick for detail retrieval.

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 'When to Use' list gives four bullets that all say the same thing – display hotel detail/booking/content pages – with no conditions that select this tool over its search/list siblings. There are no exclusions, prerequisites, or named alternatives, so it provides no routing help.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description goes beyond them by disclosing the beta status, that answers are AI-generated from the hotel's data, and that allowWebSearch pulls in external web content. It does not discuss answer accuracy, latency, or error behavior, keeping it short of a 5.

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

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

The overview is front-loaded and scannable, but the body is padded with marketing-style bullets ('Natural language responses', 'Hotel context', 'Natural language') and example questions that repeat the same point several times. Headers help structure but a fair amount of text does not add selection or invocation 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?

With no output schema, the description does explain the return shape (AI-generated, natural-language, hotel-specific answers), and it covers all three parameters and the beta caveat. Given the simplicity of a 3-parameter read-only tool, this is nearly complete; only error/edge-case behavior is unaddressed.

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 query, hotelId (MAQAMI format), and allowWebSearch (default false). The description restates these in prose ('Provide the hotelId and your question') without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The overview states a specific verb+resource: answer natural-language questions about a specific hotel using AI. It is clearly distinguishable from sibling data tools like get_data_hotel (fetch hotel record) or get_data_hotels_semantic_search, since this is a free-form Q&A endpoint.

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 'When to Use' section gives concrete scenarios (hotel Q&A, information lookup, conversational interfaces, detailed inquiries), which sets clear context. However, it never names a sibling alternative (e.g. get_data_hotel for raw fields) or states when this tool is NOT appropriate, so routing guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the description. The description adds useful context about returned content (metadata, images, IDs for rate searches) and search modes, but says nothing about pagination limits beyond the schema, rate limits, or auth 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?

It is well-structured and front-loaded with a clear Overview, but highly redundant: 'When to Use', 'What You Get', and 'Quick Start' repeatedly restate the same three or four ideas. The same information could be delivered in roughly half the text without loss.

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

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

For a 23-parameter tool with zero required parameters and no output schema, the Quick Start's advice to 'Provide search criteria (city, coordinates+radius, placeId, or hotelIds)' is genuinely helpful for avoiding an unbounded query. But it omits other valid entry points (aiSearch, hotelName, chainIds) and gives no default-behavior or result-size guidance, leaving the definition only minimally complete.

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

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

Schema description coverage is 100%, so all 23 parameters are already documented in the schema; the baseline is 3. The 'Search Options' section maps loosely to the geo/ID parameters but adds no syntax or constraint detail beyond what the schema provides (e.g., it omits chainIds, facilityIds, starRating modes).

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 ('Search and retrieve hotel listings') and enumerates what comes back (names, addresses, ratings, amenities, images, IDs). However, it never distinguishes itself from the many near-identical siblings (get_data_hotel_search, get_data_hotels_semantic_search, get_data_hotel), even though the aiSearch parameter here overlaps semantically with the dedicated semantic-search 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?

A 'When to Use' section exists, but its bullets ('Hotel listings – Display hotel search results', 'Hotel discovery – Browse hotels in specific areas') restate the overview rather than give real selection criteria. No guidance is offered on when to pick this over get_data_hotel_search or get_data_hotels_semantic_search, which is the key routing decision given the 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 already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral value beyond them: the default result count of 5 (overridable via limit), the returned fields including a relevance score, and the caution to validate name/city before using an id.

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 what it does and what it returns, then the caution and the alternative. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields and the relevance score, and explains both parameters. It omits the 20-result ceiling that lives only in the schema and does not differentiate the other semantic-search sibling, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so query and limit are already documented with the default and the example. The description restates the default of 5 and clarifies the query is semantic, but adds no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb and resource ('Find hotels by name or place') plus the mechanism (semantic text search) and routing to the more precise alternative. It distinguishes itself from get_data_hotels, though it never addresses the very similar sibling get_data_hotels_semantic_search, which an agent might otherwise 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?

Gives clear guidance for when to prefer the alternative: an exact hotel name should go to get_data_hotels with hotelName and cityName/countryCode. It also advises verifying name and city before reusing an id. It stops short of covering the other near-identical search siblings, so it is clear context but not exhaustive 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description earns credit by adding beta status, the similarity-score rounding convention, the 12km radius default, and the placeId-precedence/viewport fallback behavior — real operational 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?

Front-loaded with an Overview and useful structure, but it is bloated: 'Geographic filtering' and 'City and country filters' are each stated in the 'What You Get' list and again in their own dedicated sections, and the closing Quick Start plus beta note repeats the opening. Tighter editing would preserve all information in roughly half the length.

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 carries the burden of explaining returns (grouped hotels, room name/image URL/similarity score, hotel metadata) plus all filter modes. Nothing an agent needs to invoke it is missing, though explicit sibling differentiation would complete the picture.

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 eight parameters are already documented in the schema. The description largely restates those rules (radius default, placeId vs coordinates precedence, city/country ISO codes) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (hotel rooms) and specifies the distinctive mechanism: image-search matching of visual/text queries against room images. It implicitly separates itself from text-only siblings like get_data_hotels_semantic_search or get_data_hotel_search, but never names them, so an agent must infer the boundary.

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 'When to Use' section gives concrete triggering scenarios (visual, style-based, amenity-focused, geographic) plus example queries. It lacks any explicit when-not-to-use or a named alternative sibling, which keeps it 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 establish the safe read-only, idempotent, open-world profile. The description adds real value beyond them: beta status/subject to change, the semantic fields returned (tags, persona, style, location_type, story), relevance scores, and the hotel metadata payload — meaningful context for a tool with no output schema.

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

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

Front-loaded with an overview and useful sections, but heavy markdown scaffolding carries redundancy: four 'When to Use' bullets that say essentially the same thing, and 'Matching hotels - Hotels that semantically match your query' is a tautology. It could be roughly half the length.

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 fills the gap via 'What You Get' enumerating return fields and scores, and flags beta instability. The main remaining gap is the absence of differentiation from the other hotel-search siblings, which matters given the crowded sibling set.

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 query, limit (default 3), and min_rating (default 0). The description reinforces the query parameter and supplies concrete example queries, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (semantic/natural-language hotel search) and describes the mechanism (AI intent matching) clearly. However, it never differentiates itself from the several closely-named hotel-search siblings (get_data_hotel_search, get_data_hotel_ask, get_data_hotels), so an agent cannot tell which search to pick from the description alone.

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 a 'When to Use' section, but all four bullets restate the same idea (natural-language / intent / conversational / semantic search) rather than giving distinct conditions. No when-not-to-use guidance and no alternative tools are named, so routing among the hotel search siblings is left 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, idempotentHint, openWorldHint, and destructiveHint=false, so safety semantics are covered. The description adds little beyond that: 'No parameters required. Returns all hotel types with IDs' is useful scoping, but pagination, rate limits, and result-size behavior are unaddressed.

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 markdown sections for a no-argument reference lookup is over-structured; 'What You Get' and 'Quick Start' largely restate each other. Front-loading the core action is good, but roughly half the text is redundant.

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

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

With no output schema, the description needs to convey returns, and it does list hotel type list, numeric IDs, and type names. For a zero-parameter reference tool this is close to sufficient, though it omits any mention of ordering or completeness guarantees.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly confirms no parameters are required rather than inventing any. Nothing further is needed.

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+resource: 'Get all available hotel type classifications (e.g., resort, boutique, business hotel)', which is unambiguous. It does not explicitly distinguish itself from reference-data siblings like get_data_chains or get_data_facilities, but the referenced resource is narrow enough to be clear.

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 'When to Use' section gives three concrete contexts (type filters in search, type display, reference data for IDs), which is clear guidance. No exclusions or named alternatives are given, 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that no parameters are required and that the full airport list is returned, but says nothing about result size, pagination, or rate limits for what is effectively an unpaginated full-list endpoint.

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

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

Front-loads the Overview, but the four markdown sections are heavily redundant for a zero-parameter listing tool — 'IATA codes' and the hotel-search use case are restated in the Overview, When to Use, and Quick Start. Roughly half the text could be cut without losing 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 simple read-only reference endpoint with no output schema, the description adequately covers what data comes back (codes, names, coordinates, country codes) and that annotations handle the safety contract. The main missing piece is any differentiation from the near-identical airport/IATA 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% and the only parameter is an optional timeout, so the schema does the heavy lifting. The description's 'No parameters required' is accurate for required inputs but silently omits the timeout knob, adding no real semantic value 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 Overview states a specific verb and resource: 'Get IATA airport codes with airport names, coordinates, and country information.' An agent knows exactly what this returns. However, it never distinguishes itself from the many similar siblings (get_data_flights_airports_iatas, get_data_flights_airlines_iatas, get_data_flights_airports), which share overlapping subject matter.

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

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

The 'When to Use' section gives clear contexts (airport searches, location selection, geographic reference data). It does not name any alternative tool or state when NOT to use this one, which matters here given the crowded IATA/airport 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 already cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds value beyond them by disclosing the return shape ('codes and names') and confirming the call is parameter-free, though it says nothing about caching, rate limits, or ordering of the returned list.

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 front-loaded Overview is good, but four markdown sections for a zero-parameter reference call is heavy, and the return content (language codes and names) is restated in both 'What You Get' and 'Quick Start'. Some sentences do not earn their 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 reference endpoint with no parameters, no output schema, and full annotation coverage, the description supplies everything needed: purpose, usage contexts, and the shape of the returned data. 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?

With zero parameters the baseline is 4, and the description correctly confirms 'No parameters required,' leaving nothing ambiguous for the caller. There is no parameter detail to add beyond that.

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 Overview states a specific verb and resource: 'Get all supported languages for hotel translations and content localization.' It also names the practical purpose (language codes for API requests), which cleanly distinguishes it from the other get_data_* reference tools such as currencies or countries.

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 'When to Use' section gives four concrete triggering scenarios (language selection UI, content localization, multi-language support, reference validation). It is clear about context but never names a when-not condition or an alternative tool, which is the only thing keeping it from 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description adds a useful inventory of returned fields (text, dates, ratings, comments) but omits behavioral constraints such as the hidden cap that `language` reduces results to 10 and that `getSentiment` analyzes only the last 1000 reviews.

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 markdown section headers and four-bullet lists are padded with marketing framing ('authentic feedback ... informed booking decisions', 'Trust building', 'Decision support') that carries no operational content. Front-loading is fine, but several sentences do not earn their place.

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

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

With six parameters and no output schema, the description usefully sketches the return shape, but it never addresses pagination, result limits, or the conditional behavior of `language` and `getSentiment`. Adequate but with 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 100%, so all six parameters are already documented in the schema. The prose only echoes `hotelId` as a query parameter and adds nothing about limit/offset paging or the language/sentiment interactions, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve guest reviews and ratings for a specific hotel'), so an agent knows exactly what it returns. It does not, however, distinguish itself from nearby siblings such as get_data_hotel or get_data_hotel_ask, which also surface hotel content.

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 'When to Use' section lists product-level scenarios (review display, rating aggregation, trust building) rather than conditions that select this tool over an alternative. No sibling is named and no exclusion is given, so usage is only implied by the topic.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the identity-verification gate (bookingId + email must match) and that the voucher only appears once the booking is confirmed. Minor oddity: "returns or changes" hints at mutation for a read-only tool, but it describes the server's general check, not this tool's behavior, so it is not a 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 tight sentences, front-loaded with the core purpose before the prerequisite. 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?

With no output schema, the description compensates by naming what is returned (status, details, voucher post-confirmation) and the mandatory auth condition. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents bookingId, email and the optional lastName, including the match-check behavior. The description largely restates the required-parameter matching rule rather than adding new syntax or format guidance, so the baseline 3 for high coverage applies.

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

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

States a specific verb ("look up") and resource ("tour or activity booking") and even enumerates the payload (status, booking details, voucher once confirmed). This cleanly separates it from siblings like cancelExperienceBooking and getExperienceBookingCancelPreview without the agent needing to open any schema.

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

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

Gives a clear precondition: the `bookingId` and `email` must both be supplied and must match, otherwise the server returns nothing. It does not explicitly name alternatives (e.g. cancelExperienceBooking or the cancel-preview tool) or state when to prefer this over them, so it falls short of a full when/when-not rubric.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds real value by disclosing the authorization behavior: the server only returns or changes a booking when the id and email match, which is exactly the kind of context annotations don't carry. The word 'changes' is slightly loose against readOnlyHint but the sentence is about the auth precondition, not a write claim.

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 what the call returns and then the preconditions. No filler; every clause carries information an agent needs.

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

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

For a read-only lookup with full annotation coverage and no output schema, the description is nearly complete: it names the return fields and the auth requirement. It stops short of return format or pagination details, but those are not essential 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 description coverage is 100%, so the schema already documents all three parameters including the matching check. The description reinforces the bookingId/email pairing but adds no new syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb (look up) and resource (confirmed flight booking) and enumerates the returned contents: status, passengers, flights, booking references, fare rules and price. This lets an agent distinguish it from the generic get_bookings_bookingid and from hotel/experience booking siblings without opening any schema.

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

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

It gives a clear precondition for use — the bookingId and the email used to book must both be supplied and match — which is the key context for calling it correctly. It does not explicitly name alternative tools or when-not-to-use cases, but the scope ('confirmed flight booking') implicitly separates it from the hotel/experience booking 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 read-only, idempotent, and non-destructive, but the description adds substantial behavioral context beyond them: HTTP 409 with code 49007 when a concurrent cancellation is pending, the caveat that refunds are potential maximums not granted amounts, async refund arrival, margin-applied pricing, and the email-match auth requirement. This is unusually rich disclosure for a read 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?

Front-loaded with an Overview and well-organized headers, so the key facts come first. It is somewhat long and repeats the refund-maximum caveat in both 'What You Get' and a dedicated 'Refund amount caveat' section, which costs a point on conciseness despite the clean structure.

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 must describe return values, and the 'What You Get' section enumerates the response fields (confidence, isRefundable/isVoidable, refund/penalty, penalties[], tickets[], destination, vouchers[]) in detail. Combined with the 409/async/margin behavior, an agent has everything needed to call and interpret 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%, so bookingId, email, and lastName are already documented per-field, including the email-verification check. The description's 'Requires the bookingId and the email used to book' largely restates that, adding no new syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The Overview states a specific verb and resource: returns refund eligibility, estimated refund amounts, and penalty details for a flight booking. It explicitly distinguishes itself from the sibling post_flights_bookings_bookingid_cancellations by stating it works 'without actually cancelling it', so an agent can route correctly without opening either schema.

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

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

A dedicated 'When to Use' section names three concrete scenarios (pre-cancellation review, refund estimation, eligibility check) and positions the tool as a precursor to the cancellation sibling. The 'Concurrent cancellation' section also states the condition (already-submitted cancellation) under which the tool fails, which is explicit when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds materially beyond them: 404 for hotels without learned data, USD-denominated fixed amounts, percentage semantics, and the direct-source precedence rule along with the extra fields each entry then carries.

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?

Markdown sections are front-loaded with the overview and each bullet carries information, not filler. Slightly longer than strictly necessary for a single-parameter read tool, but nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so: it explains that each entry states inclusion in the room rate, percentage vs fixed, fixed-amount scaling granularity, and source/validity fields. An agent knows what it will get and under what failure condition.

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 hotelId's 'lp format or numeric' description lives in the schema, so the description adds no parameter-level detail. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb and resource ('Returns the tax schema of a hotel') and adds a distinguishing qualifier: normalized static data independent of the supply provider. No sibling tool covers hotel tax rules, so 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 'When to Use' section gives three concrete scenarios (price transparency, amount-due-at-property estimates, tax auditing) that clearly frame the tool's context. It stops short of naming an alternative tool or stating when not to use it, but the context is explicit.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the result feeds into an external payment flow and booking is completed outside this tool via checkoutUrl.

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 tightly written sentences with the retrieval scope front-loaded and the payment caveat second. No filler, and every clause carries information an agent needs.

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

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

With no output schema, the description compensates by enumerating the returned payload fields, and annotations handle the safety profile. For a single-parameter read this is complete enough to invoke correctly.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description restates the prebookId as an identifier and shows the URL template it populates, which adds marginal context but no new input semantics (e.g., format or validity rules).

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 (Retrieve) and resource (hotel prebook) and enumerates what is returned (final price, cancellation terms, room details, checkoutUrl). It is clearly a read of an existing prebook, but it never names its natural sibling post_rates_prebook to disambiguate create-vs-read.

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 implies the tool is used to inspect a prebook obtained elsewhere and tells the agent that payment/confirmation happens only via checkoutUrl on MAQAMI's site, which is a useful workflow hint. However, it never states when to call this versus post_rates_prebook or when a prebook expires, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuine behavior beyond that: both credentials must match or an empty result is returned, plus the shape of what comes back. It stops short of discussing rate limits or pagination for multi-booking results.

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

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

Three short sentences, front-loaded with the core purpose, then the match constraint, then the result shape, then the routing hint. No filler or restatement of the title.

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 compensates by enumerating the returned fields (bookingId, status, hotel, dates, guests, price, cancellation policy). Combined with the match precondition and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the conjunctive semantics — both email and lastName must match the booking holder and are not alternatives. That is meaningful behavior not derivable from the two independent properties.

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 ('Find'), resource ('a customer's hotel bookings') and the exact lookup keys ('email address and last name used to book'). This clearly separates it from ID-based siblings like get_bookings_bookingid and the booking-management 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 states the match precondition ('Both must match the booking holder; nothing is returned otherwise') and routes the agent to the alternative path for single-booking operations ('To look up, change or cancel one booking, use its bookingId with the same email'). When-to-use and when-to-use-something-else are both covered.

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 non-read-only, non-idempotent, non-destructive, and the description adds substantial context beyond them: the CONFIRMED-status prerequisite, that non-refundable originals yield only non-refundable alternatives, that nationality and currency are inherited from the original booking, and that the email must match the booking. It also notes this server cannot actually rebook, a meaningful behavioral limit.

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 definition is long but front-loaded and clearly sectioned under headers, so an agent can scan to the relevant part. There is some redundancy — 'Quick Start' largely restates the final step of 'How It Works' — which keeps it out of the top band.

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 100% schema coverage and no output schema, the description closes the remaining gaps by describing what comes back (prebookId, final pricing, cancellation policies, room details) and the policy-change flags cancellationChanged and boardChanged. Nothing an agent needs to invoke or interpret the call is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: alternatives are sorted by price ascending, maxPrebooks defaults to 3 and clamps above 10, and priceDifferencePercent is defined relative to the original selling price (negative = cheaper). The refundableRatesOnly override behavior is also explained in prose.

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

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

The description names a specific verb+resource (search alternative rates at the same hotel and create prebook sessions) and scopes it to a confirmed booking being 'hard amended'. It explicitly contrasts with the amend path ('rebooking is not available, so use this only to show the guest alternative prices'), which separates it from sibling put_bookings_bookingid_amend.

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?

A dedicated 'When to Use' section enumerates the three triggering scenarios (date changes, occupancy changes, hard amendments). It also states the precondition (booking must be CONFIRMED) and the server-specific fallback when a true rebooking is needed, which is exactly the when-to-use/when-not guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds the crucial behavioral constraint that the server only acts when bookingId and email match. It stops short of describing post-cancellation state or refund timing, keeping it below 5.

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

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

Two short sentences: the action first, then the mandatory pre-step, then the credential constraint. No filler, and the most important gating 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?

With no output schema, the description adequately covers the action, the required confirmation prerequisite, and auth matching. It could say what a successful cancellation returns or whether it is reversible, but for a destructive mutation whose annotations already flag destructiveness, this is close to complete.

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

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

Schema description coverage is 100%, so each parameter including the optional lastName is already documented. The description reiterates the two required params and the match requirement but adds no syntax or format detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Cancel a confirmed flight booking'), and the scoping word 'flight' distinguishes it from siblings like cancel_hotel_booking and cancelExperienceBooking without needing to open their schemas.

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 prescribes a workflow: first surface the refund estimate from `get_flights_bookings_bookingid_cancellations` and wait for a clear yes before cancelling. It names the sibling tool and the gating condition, leaving nothing 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that no card or passport details are handled here and that booking/payment happens on MAQAMI's website via checkoutUrl, which is context beyond the annotations; however it does not discuss the non-idempotent price-change behavior implied by idempotentHint=false.

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 header structure and front-loaded Overview are good, but content is duplicated across sections: fare rules and baggage are each advertised two to three times ('Fare rule retrieval', 'Booking terms', 'Fare rules'; 'Baggage policy', 'Updated baggage info'), and there is redundancy between 'Quick Start' and 'Booking'. Several sentences do not earn their place.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, enumerating the changes/pricing objects, journey pricing, fare family, baggage and booking terms, and the checkoutUrl flow. An agent has everything needed to call and interpret this one-parameter 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?

With a single parameter and 100% schema coverage, the schema already documents offerId; the description adds provenance by telling the agent to take it from post_flights_rates search results. That is meaningful routing context, though no format or error-handling detail is added.

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 operation (re-verify an existing flight offer's availability and price) plus a concrete downstream artifact (checkoutUrl). It is clearly distinguishable from the sibling search tool post_flights_rates, which is named as the source of the offerId.

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 'When to Use' section enumerates three concrete triggers (pre-booking validation, price confirmation, fare rule retrieval) and 'Quick Start' ties the input to post_flights_rates results, giving clear context. It never states an explicit exclusion or when-not-to-use case (e.g., before an offerId exists), 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 cover the safety profile (readOnly, non-destructive), so the description's additional value is in disclosing the return shape: minimum rate only, price/currency/availability, and an explicitly lighter/faster payload than the full rates call. It does not mention auth, rate limits, or error behavior, which is a minor gap for an openWorld 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?

Five markdown sections for a single lookup endpoint, with heavy repetition: 'Perfect for displaying price comparisons,' 'Perfect for listings,' and 'ideal when displaying multiple hotels' all say the same thing. The Quick Start paragraph restates parameters already covered by the schema. Front-loading is decent but the padding is substantial.

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

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

No output schema exists, but the description compensates by describing the returned fields (minimum rate, price, currency, availability), which is what an agent needs. Combined with 86% schema coverage and clear annotations, the definition is nearly sufficient, though it omits timeout usage and any error/empty-result behavior.

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 86%, so the schema already documents nearly every parameter including date format, currency, and occupancy structure. The description only restates 'hotel IDs, dates, and guest occupancy' and claims parameter parity with the main rates endpoint, adding minimal semantics 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 (get) and resource (cheapest available rate for each hotel) and explicitly scopes it against the fuller alternative, noting the same parameters as 'the main rates endpoint.' An agent can distinguish this from post_hotels_rates without opening either schema.

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

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

The 'When to Use' section gives concrete contexts (listing pages, quick comparisons, price sorting) and a when-not condition ('when you only need the lowest price, not all rate options'). It implies rather than names the sibling post_hotels_rates, so it falls just short of fully explicit 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?

With annotations already covering readOnly/openWorld/idempotent/destructive, the description adds substantial non-obvious behavior: recommended timeout of 6-12s, default limit of 200 (expandable to 5,000), incremental streaming mode, the `sessionId` price-consistency contract, and the caveat that pagination via `offset` skips passed hotels rather than returned results. It also warns that `maxRatesPerHotel` caps before room mapping.

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 markdown structure is front-loaded and scannable, opening with Overview, When to Use, then What You Get. The price-consistency guidance is duplicated across 'Key Features' and the Quick Start tip, and the bullet-heavy formatting makes it longer than strictly necessary, but nearly every line earns its place for a 42-parameter tool.

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

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

For a 42-param search tool with no output schema, the description compensates with a 'What You Get' section describing rates, room options, booking details, and hotel data. It covers required inputs, location-method alternatives, and performance defaults. Minor gaps remain around response ordering, error behavior, and timeout defaults, but nothing an agent needs to construct a valid call is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 42 parameters thoroughly. The description mostly restates the required fields and the `includeHotelData` tip rather than adding new semantics; the one genuinely additive piece is the `sessionId` usage pattern (unique per session, reused with the same checkin/checkout). Baseline 3 is appropriate when the schema carries the load.

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 ('Search for hotel rates and availability') and positions the tool precisely as 'your primary endpoint for finding bookable hotel rooms with real-time pricing.' It differentiates itself from data-lookup siblings by noting hotel IDs come from `get_data_hotels` or `get_data_hotel_search`, and it enumerates the search methods it supports.

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 'When to Use' section gives four concrete scenarios (listing pages, detail pages, multi-room bookings, filtering) and the Quick Start names the required fields and the alternative location methods. However, it never explicitly contrasts with the closest sibling, `post_hotels_min_rates`, nor states when not to use this tool, leaving some routing inference to the agent.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful context the annotations cannot convey: this only locks a rate, takes no payment details, and does not confirm the booking — payment happens on MAQAMI's website via the returned checkoutUrl. It omits any mention of how long a lock survives or expiry 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?

Sectioned with headers (Overview/When to Use/Quick Start/What You Get/Payment) and front-loaded with the core action. The 'What You Get' list is efficient, though the prose is slightly longer than strictly 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?

No output schema exists, but the description compensates by enumerating the return payload (prebookId, price, terms, checkoutUrl) and explaining the downstream flow. With annotations covering safety and 75% schema coverage on params, only the undocumented `timeout` leaves a 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 75%, so bedTypeIds and voucherCode are already documented in the schema. The description reinforces that offerId must come from post_hotels_rates 'exactly as it was returned', adding a real constraint, but the undocumented `timeout` parameter is addressed nowhere. 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?

States a specific verb and resource — 'Locks the chosen hotel rate' — and enumerates the exact outputs (final price, cancellation terms, checkout link). It is clearly distinguished from siblings by naming post_hotels_rates as the source of the offerId and get_prebooks_prebookid as the retrieval counterpart.

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 'When to Use' section gives a concrete precondition (customer has chosen hotel, room, dates, guests and reviewed price/terms) and the 'Quick Start' names the upstream tool post_hotels_rates. It does not state when-not to use this or name an alternative prebook path, 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 declare the safety profile (destructiveHint=true, idempotentHint=true), and the description adds genuinely new behavioral context: the server only changes a booking when bookingId and the original email match, and the agent should confirm new details with the customer before calling. It does not explain what 'destructive' means here (holder data is overwritten and not reversible), which keeps it short of a 5.

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

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

Three short, front-loaded paragraphs: scope of change, alternative tool, then how to call it. Minor redundancy in restating the bookingId/email verification requirement in two places costs it the top mark.

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 mutating tool with no output schema, the description covers scope, exclusions, alternative routing, required inputs and a pre-call confirmation step. Only the consequence of the destructive overwrite is left unspecified.

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 every parameter including the current-vs-new email distinction. The description restates the required triple (bookingId, email, holder) but adds no syntax, format or constraint detail beyond what the schema already 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?

States a specific verb (correct), resource (booking holder's name, email or phone) and scope constraint (on a confirmed hotel booking). It explicitly names the sibling it is not (post_bookings_bookingid_alternative_prebooks), so an agent can differentiate without opening schemas.

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 the intended use case ('fix a typo'), explicit exclusions ('does not change dates, rooms or guests'), and a named alternative with the condition that selects it ('to show the customer prices for other dates or guests'). Nothing is left to inference.

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