MAQAMI Travel

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

The description explicitly states 'Idempotent on chargesId' and details replay behavior (HTTP 200 on already-confirmed, 409/45035 on concurrent confirm), but the annotations declare idempotentHint=false. This directly contradicts the structured hint and could mislead an agent into replaying the call.

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 headers (Overview, Access, Idempotency, When to Use, Constraints) make it easy to scan and the key purpose is front-loaded. It is somewhat verbose for a 3-parameter tool, but each section carries distinct 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 mutation tool with no output schema and 3 required nested params, the description covers access gating (support-team enablement), idempotency/replay semantics, error codes, and required vs optional fields. An agent has everything needed to invoke it correctly, aside from the annotation conflict.

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 already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: only chargesId + payment are needed (lines encoded in chargesId), payment.method must match the booking's original payment, and transactionId must be the id from precharges.

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 ('Confirms a pending extra-charge batch created by /extra-charges/precharges') and describes the side effects (Stripe capture, credit-line billing, appending lines to the booking). An agent can clearly distinguish it from the sibling prechargeFlightExtraCharges, which creates the batch this tool confirms.

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 an explicit precondition (after the customer confirmed the PaymentIntent at requires_capture/succeeded, or immediately for CREDIT bookings) and the Overview names the upstream tool that produces chargesId. Alternatives and timing are fully specified.

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

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

Beyond the annotations it discloses non-obvious behavior: cart status `completed` maps to dispatcher `PENDING_CONFIRMATION`, final `CONFIRMED` arrives via webhook, and `ERROR` returns 502 – all essential for interpreting a non-idempotent, open-world mutation. It also explains that responses expose partner sell in `price` and earn in `commission`/`clientCommission` while `providerPayment` is omitted, which is real behavioral context not present in 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 the core action and then the status/response semantics in compact sentences; every sentence carries information. The price/commission note is slightly tangential but still useful for interpreting the return value.

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

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

For a mutation tool with no output schema and 40% param coverage the description supplies the crucial missing pieces: async confirmation flow, error mapping, and response field semantics. It leaves the billing/traveler payloads and the prebook-prerequisite unsaid, but the core operational picture is 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 only 40% and the description adds no parameter-level semantics for `billing`, `traveler`, or `customTags`; it only alludes to the payment step already documented by the schema's `transactionId` note. With the majority of parameters undocumented in both places, the description does not compensate for the coverage gap.

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 gives a specific two-step verb sequence (capture Stripe payment, confirm cart with experiences-api) and names the concrete resource (cart/prebook). It clearly implies the post-prebook booking step, though it never names a sibling like prebookExperienceTour to differentiate explicitly.

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

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

Usage is implied: it consumes a prebookId from the prebook endpoint and completes the booking, and it hints that CONFIRMED arrives asynchronously via webhook. But there is no explicit when-to-use vs. when-not, no stated prerequisites (e.g. must call prebookExperienceTour first), and no routing to an alternative.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds useful context that deletion is permanent and cannot be recovered, plus that a confirmation is returned. It does not mention authentication requirements or edge cases like a missing voucher, but it meaningfully supplements the annotations.

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

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

The markdown structure is clear and front-loaded, but it contains redundancy across Overview, Important Notes, and Quick Start regarding permanent deletion. Several sentences restate the same caution, so it is longer than necessary for a single-parameter delete 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 simple delete operation with one documented parameter and full annotation coverage, the description is nearly complete. It tells the agent what the tool does, when to use it, and that it returns confirmation, though it could note failure behavior or prerequisites.

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 id parameter is already documented. The description adds value by specifying that the voucher ID must be provided in the URL path, which goes beyond the schema and clarifies 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 description clearly states a specific verb and resource: 'Permanently remove a voucher from your system.' It distinguishes the destructive nature of the operation, but it does not explicitly contrast this tool with siblings like put_vouchers_id_status or get_vouchers_voucherid.

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: cleanup, error correction, and inventory management. It lacks any 'when not to use' guidance or explicit alternatives, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered and the description needn't repeat it. The description adds scoping context (results tied to your API key, optional stay vs. booking creation filters) but omits pagination, result caps, sorting, or rate-limit behavior for a potentially large listing.

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 with headers, but heavily over-formatted for a simple list tool: four sections, bulleted marketing phrasing ('Perfect for generating reports', 'Administrative overview'), and a redundant Quick Start that repeats the zero-parameter case. The signal-to-length ratio is mediocre.

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

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

Covers what the tool returns at a high level (complete booking list, full details, status) and the filter categories, which is useful since there is no output schema. However, it never addresses result volume, pagination, or ordering — material gaps for a tool that can return 'all bookings' on an account.

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 eight parameters, including the overlap semantics for startDate/endDate and the customTags syntax. The description only restates a subset (stay period, booking period, status) and omits paymentStatus, customTags, and sandbox, adding little beyond the schema — baseline 3.

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

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

States a specific verb and resource ('Get all bookings associated with your API key') with clear scope (all bookings under the key, optional date filtering). It does not, however, differentiate itself from overlapping siblings like listBookings, searchBookings, or get_bookings_bookingid, so an agent cannot tell from the text alone which retrieval tool to pick.

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 use cases (reports, date-range queries, administrative overview, analytics), which gives implied context for invocation. But it offers no 'when not to use' and never names an alternative, despite several sibling list/search tools that plausibly overlap. Guidance is present but does not resolve tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. With no output schema, the 'What You Get' section meaningfully discloses the return payload (status, guest info, pricing breakdown, cancellation policy, hotel confirmation code). No mention of auth requirements or behavior on an invalid/missing booking 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?

Front-loaded and well-sectioned, but padded: the overview already says it returns 'status, guest details, pricing, and cancellation policies,' which the 'What You Get' bullets then restate in six lines. For a single-ID getter, the markdown is longer than the task warrants.

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-by-ID tool with full annotation coverage, the definition covers purpose, contexts, and response contents adequately, and no output schema means return values do not need separate treatment. It omits error/not-found behavior, 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 the baseline is 3. The description adds only that bookingId goes in the URL path; it does not clarify the timeout parameter or the ID format. Note the schema's own bookingId description says 'booking you would like to update,' which conflicts with this read operation, but the description correctly frames it as a lookup.

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 complete details for a specific booking by its booking ID.' That distinguishes it in kind from list/search siblings like get_bookings and searchBookings, though it never explicitly names an alternative. Clear and specific, but no direct sibling differentiation.

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

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

The 'When to Use' section gives four concrete contexts (details page, status checks, confirmation lookup, support queries), which is solid situational guidance. It stops short of naming when NOT to use it or pointing to the list/search siblings for broader queries.

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, non-destructive, open-world behavior, so the bar is lower. The description still adds real context: the previous period is auto-derived as an equal-length window immediately before, and new nationalities return previous_period: null with change expressed as 100% growth — useful edge-case behavior the annotations do not convey.

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

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

Markdown headers front-load Overview, When to Use, What You Get, and Quick Start, and the content is scannable. It is longer than strictly necessary for a three-parameter read tool, with some overlap between 'What You Get' and the overview paragraph, but nothing is wasted.

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 thoroughly covers the return shape: period metadata, summary totals, per-nationality booking/sales/average metrics, and the new-market null case. Combined with the annotations covering safety, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it names from/to/sandbox as the query inputs and explains that the API derives the prior comparison period from them rather than requiring a separate parameter.

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

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

The description states a specific verb and resource: analytics on guest-nationality source markets of bookings, with period-over-period comparison. It is clear what the tool produces, but it does not differentiate itself from the very similar sibling get_bookings_source_markets_report, so an agent must guess which report to pick.

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?

Four explicit 'When to Use' bullets give concrete scenarios (source market analysis, period comparison, geographic dashboards, marketing planning), which is well above implied usage. It stops short of an exclusion or an alternative-tool pointer, which would be needed for a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so safety is covered. The description adds real behavioral context: automatic derivation of the previous period of equal length, ordering by current-period sales, limit-bounded output, and the null previous_period for new hotels. Does not mention rate limits or pagination beyond '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?

Markdown headers (Overview, When to Use, What You Get, Quick Start) front-load purpose and usage. Content is a bit long with some overlap between Overview and Quick Start, but every section earns its place for an analytics endpoint. Slight redundancy keeps it from a 5.

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

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

No output schema exists, yet the 'What You Get' section documents the return shape in detail (period metadata, summary totals, per-hotel fields, nulls for new properties). This compensates well for the missing output schema. It still omits guidance on limits, defaults, or authentication, so it's complete but not exhaustive.

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. The description goes beyond the schema by explaining that the previous period is auto-derived from from/to and that limit ranks by current-period sales, adding semantic value about how from/to and limit interact with the result set.

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: returns hotel-level sales analytics (sales, buying price, profit, margin) with period-over-period comparison. Scope is concrete and concrete metrics are named. However, it never contrasts itself against closely related siblings like post_analytics_hotels or getPriceIndexHotels, so an agent can't tell from the description alone which of these to call.

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' block gives implied usage (property performance, period comparison, profit analysis, dashboards) but does not name alternatives or exclusion conditions, e.g., when to prefer post_analytics_report or post_analytics_markets. Useful but not decisive for sibling selection.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the bar is lower, yet the description adds real substance: the previous period is auto-derived (not supplied), and new/inactive destinations appear with previous_period:null or zeroed values with negative change. That edge-case disclosure is genuinely useful. It does not discuss pagination or row 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?

Markdown headings keep it scannable and the Overview is front-loaded with the core concept. It is slightly padded - 'Quick Start' largely restates what the Overview and 'What You Get' already convey - but nothing is confusing.

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 the 'What You Get' section enumerates period metadata, summary totals, and per-destination metrics including null handling. That is sufficient for correct invocation and interpretation; row caps and ordering are the only omissions.

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 baseline is 3, but the description adds meaning beyond the schema by stating that from/to define the current period and that the API derives the matching previous period, plus noting sandbox is a query parameter. This tells the agent why there is no previous-period argument.

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 in the Overview ('Returns analytics on destinations') and defines the key scope: destination = hotel country, current vs previous equal-length period. It is clearly separable from siblings like get_bookings_hotels_sales_report or get_bookings_guest_nationality_report by its destination-country focus, though it never names those siblings explicitly.

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

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

The 'When to Use' section gives four concrete scenarios (destination performance, period comparison, geographic dashboards, inventory planning), which is strong context. It stops short of explicit when-not-to-use guidance or naming the alternative report tools an agent should pick instead.

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

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

Annotations already declare this a safe, idempotent, open-world read, so the description's burden is reduced. It usefully adds that no parameters are required, that the full chain list is returned with numeric IDs, and the intended downstream use of those IDs — behavior the annotations cannot express, and valuable 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?

The markdown headers make it skimmable and the key line is front-loaded, but four sections restate the same single idea (returns all chains, IDs usable in filters) with heavy repetition. For a zero-parameter reference endpoint, 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 and no parameters, the description must carry the return-value burden, and it does — it enumerates chain list, IDs and names explicitly. Complete enough to call correctly; only the relationship to get_data_hoteltypes is left 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?

There are zero parameters, so the baseline is 4 per the rubric. The description reinforces this with 'No parameters required,' leaving no ambiguity that this is a no-argument listing call.

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' with concrete examples (Marriott, Hilton, IHG) — and ties it to chain filtering in hotel searches. It is clearly distinguishable from get_data_hotels/get_data_hotel_search, though it never explicitly differentiates itself from the near-neighbour get_data_hoteltypes, which an agent could plausibly 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 (chain filters, brand selection, reference data), which is more than most sibling definitions offer. It stops short of exclusions or naming an alternative tool, so it is clear context without routing rules.

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, non-destructive, and openWorld, so the safety profile is covered. The description adds the ISO-2 requirement and that all cities for a country are returned, but says nothing about rate limits, result size, ordering, or error behavior.

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

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

Front-loaded and skimmable via headers, but the 'What You Get' bullets ('City list', 'City names') are redundant filler for a simple list endpoint, and the use-case bullets overlap heavily. Not wasteful enough to drop below 3, but not tight either.

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-required-parameter read-only list tool with full annotation coverage and no output schema, the description is largely sufficient: it names the input format and the companion endpoint. Missing only minor details like result ordering or volume.

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

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

Schema coverage is 100% and both parameters are documented in the schema itself. The description reinforces ISO-2 format with examples ('US', 'GB') and points to the country-code endpoint, which is mildly useful but largely restates 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 and resource: 'Get a list of all cities within a specific country.' This clearly distinguishes it from siblings like get_data_countries or get_data_places, which cover different geographic resources.

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 gives concrete contexts (dropdowns, location filters, autocomplete) and the Quick Start explicitly routes to the country list endpoint to obtain countryCode. It lacks any 'when not to use' or sibling-alternative guidance, which keeps 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 is fully covered. The description adds value the annotations cannot: it discloses the exact payload shape (all countries, ISO-2 codes, full names) and that no parameters are needed, which matters since there is no output schema. It stops short of mentioning caching, rate limits, or result size.

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 front-loaded with the Overview first, but for a trivial no-argument lookup the content is inflated into five markdown sections. 'What You Get' and 'Quick Start' restate the same facts (country list, ISO-2 codes, no parameters) already given in the Overview, so 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?

For a simple read-only reference endpoint, the description covers purpose, use cases, returned fields, and the fact that no input is required. With annotations handling behavioral hints and no output schema to lean on, the description supplies nearly everything an agent needs; only caching/pagination-style operational details are absent, which is low impact here.

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 optional 'timeout' parameter, so the schema fully documents it and the baseline of 3 applies. The description's 'No parameters required' is consistent with the zero-required-parameter reality but adds nothing the schema does not already convey.

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 a complete list of all countries... with their ISO-2 country codes') and names the returned data precisely. It is clear what the tool does, but it never explicitly distinguishes itself from the many sibling reference-data tools (get_data_cities, get_data_currencies, get_data_languages), so an agent must infer the boundary from the resource name 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?

The 'When to Use' section gives four concrete scenarios (dropdowns, location filters, form inputs, reference data for other endpoints), which is solid context for an agent deciding when to reach for this tool. It offers no exclusions or named alternatives, so it stops short of the explicit when-not guidance that would warrant 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 fully covered elsewhere. The description adds that the call takes no required parameters and returns the full currency set, but omits pagination, caching, or list-size behavior — modest added value on top of rich annotations.

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

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

The markdown-heavy format is bloated: the 'What You Get' bullets (currency list, codes, names, country mapping) simply restate the Overview sentence verbatim, and the Quick Start repeats it a third time. Front-loading is fine, but substantial space 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?

For a parameterless reference lookup with no output schema, the description usefully enumerates the returned fields (ISO codes, names, country mappings), which an agent could not otherwise infer. Nothing critical is missing, though list size and ordering are 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?

Only one optional parameter (timeout) with 100% schema description coverage, so the schema already carries the burden. The description's 'No parameters required' is accurate about requiredness but adds no syntax or default guidance beyond what the schema provides.

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

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

States a specific verb and resource ('Get all available currencies') with the exact payload: codes, names, and country mappings. It is distinguishable from siblings like get_data_countries and get_data_languages by resource, though it never names an adjacent tool explicitly.

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

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

The 'When to Use' section gives four concrete scenarios (dropdowns, price display, conversion, reference data for booking endpoints), which is clear context for invocation. It stops short of explicit exclusions or named alternatives (e.g., 'use get_data_countries for country data'), 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that it returns the full facility set with multi-language names, but discloses no pagination behavior, response size, or caching/rate-limit traits beyond that. With annotations carrying the main burden, a 3 is appropriate.

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

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

It is front-loaded with an Overview and Quick Start, but the 'What You Get' bullets are redundant: 'Facility names in multiple languages' and 'Localized facility names' say the same thing, and multi-language support is listed twice across sections. For a zero-parameter tool this is noticeably padded.

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

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

With no output schema, the description must describe the return, and it does (facility list, numeric IDs, multi-language names). For a trivial zero-param read-only reference lookup this is essentially complete, though it omits any indication of list size or ordering.

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 parameter semantics default to baseline 4. The description correctly reinforces 'No parameters required', matching the empty 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+resource: 'Get all available hotel facilities (amenities) with multi-language translations.' It immediately clarifies this is reference data distinct from the hotel/type/language lookups among its siblings. An agent knows exactly what resource it returns.

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 use cases (facility filters, facility display, multi-language support, reference data). It provides clear context for invocation but names no alternatives or exclusions, so it stops short of the explicit when/when-not routing needed for a 5.

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

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

Annotations already establish readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: what fields come back (name, IATA/ICAO, country, alliance, logo), that no parameters means 'all airlines', and how each filter narrows results. Pagination/limit default behavior is the one undisclosed trait.

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 headers are front-loaded and scannable, but a README-style structure with four sections is heavy for a four-parameter read-only list call. 'What You Get' largely restates the Overview's filter list, so several bullets 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 in play, the description correctly compensates by enumerating returned fields and default behavior, and it explains every filter. The only real gap is result-size/limit semantics for a list endpoint that could return the full airline directory.

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

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

Schema description coverage is 100% with an enum and worked example ('AA' or 'American'), so the schema carries most parameter meaning. The description's added value is modest — it maps enum values to human-readable alliance names, which is helpful but not essential given the schema already enumerates them.

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 its filter dimensions, so an agent immediately knows what the tool returns. It does not, however, differentiate itself from the very close sibling get_data_flights_airlines_iatas / _iatacode, so the boundary must be inferred from names 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?

A dedicated 'When to Use' section gives three concrete scenarios (directory listing, alliance filtering, active-only retrieval) and a Quick Start that tells the agent the no-parameter default. It never names or excludes the sibling airline IATA tools, so alternative-selection 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, destructiveHint=false, and openWorldHint, so the safe-read profile is fully covered by structured data. The description adds only the activeOnly filter behavior and the 'lightweight' nature of the response; it says nothing about result size, ordering, or whether the list is paginated.

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 with headings, but the formatting is disproportionate to a one-parameter read tool. The Quick Start sentence largely repeats the Overview and What You Get sections, so several lines 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 burden of describing returns, and the 'What You Get' section does name the two returned fields (IATA codes and names). It is adequate for a trivial list endpoint, though it omits response shape and size expectations.

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 boolean parameter is already documented in the schema. The description restates the same semantics ('Use activeOnly=true to filter out inactive airlines') without adding format or edge-case detail, so it neither helps nor hurts beyond the baseline.

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

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

The overview names a specific verb and resource: retrieve a lightweight list of airline IATA codes with names. The word 'lightweight' implicitly contrasts it with the heavier sibling get_data_flights_airlines, but that sibling is never named, 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?

A dedicated 'When to Use' section lists three concrete scenarios (autocomplete, client-side filtering, code validation), which is clear context. However, it never names an alternative tool or an exclusion condition, so routing among get_data_flights_airlines, get_data_iatacodes, and get_data_flights_airlines_iatas_iatacode 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description earns credit beyond that by enumerating the returned metadata (name, IATA/ICAO, country, alliance, logo URL, active status) — valuable given 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?

Markdown headers front-load the purpose and usage before the payload description. It is slightly heavier than needed for a one-parameter lookup, but each section (usage, return fields, quick start) carries information an agent would otherwise lack.

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 correctly compensates by describing return fields, and the quick start shows the required path parameter. Nothing essential for calling or interpreting the result 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% and the single iataCode parameter is already documented as a 2-letter code with the 'AA' example. The description restates the same format guidance without adding syntax, validation, or lookup-failure semantics, so it is the expected baseline rather than an enhancement.

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 (full details for a specific airline) keyed on the 2-letter IATA code. The 'specific airline' phrasing implicitly separates it from the sibling list endpoint get_data_flights_airlines_iatas, which enumerates codes rather than fetching one.

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' block gives three concrete scenarios (airline display, flight result enrichment, code validation). It lacks any when-not guidance or explicit reference to the sibling list/detail tools, so an agent must infer that this is the single-record variant.

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 this a safe, idempotent, open-world read, so the safety profile is covered. The description goes beyond them by disclosing that results are relevance-ranked and what fields come back (IATA code, city/country, coordinates), though it says nothing about empty-result behavior, rate limits, or pagination.

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

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

Markdown headers make it scannable and the core instruction is front-loaded in the Overview and Quick Start. The 'What You Get' and 'When to Use' sections are somewhat padded for a one-parameter lookup, but each section carries usable information.

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

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

With no output schema, the description usefully describes the return contents and downstream usage (IATA codes feeding legs[].origin/destination), which is the right compensation. It omits result-limit and error handling details, but nothing critical to calling the tool correctly is missing.

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

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

Schema description coverage is 100% for the single parameter, so the schema already documents the query string, its 2-character minimum, and examples. The description repeats the 2-character minimum and adds example formats, but adds no syntax or matching semantics beyond the schema – baseline 3.

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

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

The description states a specific verb and resource: 'Search for airports by name, city, or IATA code using a text query.' Scope (returns matching airports for autocomplete/search) is clear. It stops short of explicitly distinguishing itself from close siblings like get_data_flights_airports_iatas or get_data_iatacodes, 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?

A dedicated 'When to Use' section gives three concrete scenarios (autocomplete, discovery, pre-search validation), which is clear context for invocation. However, it never names an alternative tool or states when NOT to use this one, leaving the sibling-selection decision to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuine context beyond that: the payload is 'lightweight', contains codes plus names, and is intended to be downloaded once and filtered client-side, implying no pagination. It still omits any statement about result size or rate limits for a full-table 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?

Front-loaded 'Overview' followed by clearly labelled sections; an agent can skim and act. There is mild redundancy (the code/name return content is restated in both 'What You Get' and 'Quick Start'), and the section scaffolding is heavy for a one-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?

With no output schema, the 'What You Get' section usefully compensates by naming the returned fields. However, it leaves the required-vs-optional parameter question ambiguous and says nothing about result volume or pagination for a full airport list, so an agent calling it correctly still has avoidable uncertainty.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add meaning by explaining that `q` filters by name OR code, beyond the schema's bare 'Search query'. But it also states 'Call with no parameters to get all airport codes and names' while the schema marks `q` as required and additionalProperties=false, which could push an agent into an invalid call.

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 a lightweight list of airport IATA codes paired with names. An agent immediately knows this is a bulk code/name lookup. However, it never distinguishes itself from close siblings such as get_data_flights_airports, get_data_flights_airports_iatas_iatacode, or get_data_iatacodes, so the 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 three concrete scenarios (autocomplete, client-side filtering, code validation), which is clear context beyond mere implied usage. It never states when NOT to use it or names an alternative sibling. The instruction 'Call with no parameters' conflicts with the required `q`, which undercuts the guidance at invocation time.

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, open-world, so the safety profile needs no repetition. The description adds genuinely non-structured context by enumerating the returned fields (name, city, country, timezone, IATA/ICAO, coordinates) in the absence of an output schema. It omits error behavior for an unknown code and any rate limits, keeping 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?

Structure is well front-loaded, but for a one-parameter lookup the four markdown sections are heavy and partly redundant: 'country and city' appears in both 'What You Get' and the following bullet, and 'Quick Start' repeats the schema's own example. Trimming one or two bullets would lose nothing.

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?

Purpose, usage scenarios, and returned fields are all covered for this simple read-only lookup, and annotations remove the need to explain safety. Only failure modes (unknown/invalid IATA code) are unaddressed, a minor gap for a tool this simple.

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 parameter, so the schema already documents iataCode fully. The description only restates the format and adds the JFK example (also in the schema) plus a note that it goes in the URL path, adding marginal value. 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 (Retrieve) plus resource (detailed information for a specific airport) and the key (3-letter IATA code), which cleanly separates it from the sibling list endpoints get_data_flights_airports and get_data_flights_airports_iatas. An agent can pick between them 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 three concrete scenarios (display, flight-result enrichment, autocomplete validation), which is clear positive guidance. It stops short of an explicit when-not-to-use or naming the sibling list tool to use instead when you lack a code, 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 readOnly, idempotent, non-destructive, openWorld behavior, so the safety profile is covered. The description adds genuine value by enumerating the returned payload (amenities, images, location, ratings, chain/star metadata), which matters since no output schema exists. It does not mention error cases (e.g. unknown hotelId) or rate 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?

The markdown scaffolding is heavy and much of it is redundant: 'What You Get' largely repeats the Overview's list of descriptions/amenities/images/location/ratings, and the four 'When to Use' bullets say essentially the same thing. The signal could be conveyed in a third of the text.

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 compensates by listing returned fields, and it covers the required hotelId call path. However, it says nothing about the three optional parameters' effect (language, timeout, advancedAccessibilityOnly) or failure behavior, so it is adequate rather than 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 the schema already documents all four parameters including language, timeout, and advancedAccessibilityOnly. The description only references hotelId as a query parameter and adds no format or semantics beyond the schema, fitting the baseline of 3.

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

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

The Overview states a specific verb+resource: 'Get comprehensive details about a specific hotel.' It clearly distinguishes a by-ID detail lookup from list/search siblings like get_data_hotels and get_data_hotel_search, but it never names those siblings explicitly, leaving the differentiation to inference.

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 four scenarios, but they are near-identical restatements ('hotel detail pages', 'hotel profiles', 'content display') rather than decision criteria. No alternative tool is named and there is no 'when not to use' guidance, 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, non-destructive, so the safety profile is covered. The description adds genuinely new context (beta status subject to change, web-enhanced answers via allowWebSearch), but says nothing about answer reliability, latency, or failure modes for an AI-answer tool.

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

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

The markdown-heavy structure is far longer than a 3-parameter read tool warrants, with heavy redundancy ('natural language' is asserted in the overview, what-you-get, and key-features sections). The core instruction is buried in the final 'Quick Start' section.

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 adequately (AI-generated natural-language answers grounded in hotel data), plus example questions clarify expected input. Coverage is good for a simple read-only tool, only lacking answer-quality caveats.

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

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

Schema description coverage is 100%, so all three parameters are already documented, making 3 the baseline. The description only restates hotelId, the question, and allowWebSearch, and inconsistently refers to the question as `question` while the schema names it `query`, adding mild ambiguity rather than meaning.

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: ask natural-language questions about a specific hotel and receive AI-generated answers. This is clearly distinguishable from data-listing siblings like get_data_hotel or get_data_hotels, though no sibling is named explicitly.

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

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

The 'When to Use' section lists four scenarios (Q&A, information lookup, chat interfaces, detailed inquiries), which implies usage context. However, these are largely restatements of the same idea and there is no guidance on when to prefer this tool over get_data_hotel or get_data_hotel_search, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that results are metadata-only (names, addresses, ratings, amenities, images, IDs) and notes hotel IDs feed rate searches, but says nothing about pagination behavior or result-size constraints beyond what the schema already documents.

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 scannable, but there is heavy redundancy: 'Hotel listings', 'Metadata retrieval', 'complete metadata', and 'matching hotels with complete metadata' repeat the same point across Overview, When to Use, What You Get, and Quick Start. The content could be roughly halved 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 23-parameter, zero-required search tool with no output schema, the description correctly signals that a search criterion must be supplied and sketches the return shape. However, it does not warn about the maximum limit, the default 200-result cap, or mutual exclusivity between criteria, leaving gaps an agent would hit in practice.

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 every one of the 23 parameters is already documented in the schema, including limit/offset defaults, radius minimum, and placeId semantics. The description's high-level 'Search Options' map adds no syntax or format detail beyond that, 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 ('Search and retrieve hotel listings') and enumerates the returned metadata. It is clear on its own, but it never names or differentiates itself from close siblings like get_data_hotel_search, get_data_hotels_semantic_search, or get_data_hotel, so an agent must guess which hotel-lookup tool to call.

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' and 'Search Options' sections restate the same idea (search by city, coords, placeId, hotelIds) four different ways rather than giving conditions that select this tool over alternatives. No exclusions or sibling routing is provided, 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 establish read-only, open-world, idempotent, and non-destructive behavior. The description adds the return shape—best match with basic details and a relevance score—but does not disclose auth needs, rate limits, or error behavior beyond what annotations cover.

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 tool's purpose and followed by a brief return summary. There is no wasted text.

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

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

For a simple one-parameter read-only search tool with rich annotations and no output schema, the description adequately covers invocation and return expectations. The main omission is routing clarity against similar sibling tools.

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

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

There is one parameter with 100% schema description coverage, and the schema already explains it with an example. The description restates that it is a semantic text query but adds no syntax, format, or constraint details beyond the structured field.

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 gives a clear verb and resource: search for a hotel using a semantic text query, returning the best-matching hotel. It is specific, but it does not distinguish itself from similar siblings such as get_data_hotels_semantic_search or get_data_hotel_ask.

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 usage when a semantic text query is available, but provides no explicit when-to-use guidance, no exclusions, and no comparison to alternatives. With many sibling hotel lookup tools, this leaves routing ambiguous.

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. The description adds significant context beyond that: it identifies the feature as beta, describes the image-search technology, details the return structure (hotels grouped by ID with room details and similarity scores), and explains geographic filtering behavior including defaults and viewport precedence. This is valuable behavioral disclosure.

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

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

The description is well-structured with markdown headers and bullet lists, making it easy to scan. However, it contains some redundancy—'Geographic filtering' and 'City and country filtering' are listed in both 'What You Get' and separate sections—which slightly detracts from conciseness. Still, it is appropriately sized for a tool with 8 parameters and a beta caveat.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns, including hotel metadata and similarity scores. It also covers all major usage scenarios and geographic filtering modes, and the annotations cover safety. The only minor gap is the lack of sibling differentiation, but the description is otherwise complete for an agent 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%, so the schema already fully documents all 8 parameters. The description reinforces some parameter usage (query types, geographic filtering) but does not add syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb (Search) and resource (hotel rooms) with a clear scope (visual and text-based queries). It distinguishes from generic hotel search by focusing on rooms and visual matching, but does not explicitly name any sibling tools to differentiate from them, so it lacks that final level of specificity.

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 five concrete scenarios for using this tool, providing clear context. However, it does not state when not to use it or name alternative tools like get_data_hotels_semantic_search, leaving the agent to infer selection criteria.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context: beta status with a stability caveat, and the shape of what is returned (semantic attributes, relevance scores, metadata). No auth or rate-limit notes, hence not 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?

Front-loaded with a clear overview, but the markdown scaffolding is heavy and several ideas repeat: intent-based matching appears in Overview, When to Use, and Quick Start, and 'semantically match' is restated three times. Readable 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?

With no output schema, the 'What You Get' section usefully documents the return payload (hotels, semantic attributes, relevance scores, metadata), which is exactly what's needed. The beta caveat is disclosed. Only the lack of sibling disambiguation keeps it from a 5.

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 all three parameters are documented in the schema (query, limit, min_rating), so baseline 3 applies. The description reinforces the natural-language nature of query with example phrases but adds no syntax or constraint detail beyond the schema.

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

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

States a specific verb and resource (semantic hotel search via natural language) and clearly frames the differentiator: meaning-based matching rather than keywords. An agent can distinguish this from get_data_hotels, get_data_hotel_search, and get_data_hotels_room_search 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?

The 'When to Use' section gives clear triggers (natural language, intent-based, conversational, semantic matching) plus concrete example queries, so the agent knows the context for invoking it. However, it never explicitly routes against the nearest siblings (e.g. get_data_hotel_search or get_data_hotels), leaving the choice 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, destructiveHint=false, and openWorldHint, covering the safety profile. The description adds useful context that it takes no parameters and returns all types with numeric IDs. With annotations carrying the behavioral 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?

Four markdown sections (Overview, When to Use, What You Get, Quick Start) are used to convey one simple fact: this returns all hotel type IDs with no input. 'When to Use' and 'What You Get' substantially overlap, and the Quick Start repeats the same claim again.

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 no-parameter reference-data lookup with no output schema, the description tells the agent what it returns (type IDs and names) and how to use them. Nothing critical is missing, though the repetition dilutes signal.

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. The description correctly notes 'No parameters required,' which is all that is needed for an empty 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+resource: retrieving all hotel type classifications (resort, boutique, business hotel). The resource is clearly distinct from sibling reference-data tools like get_data_hotel, get_data_facilities, and get_data_chains, though it never explicitly contrasts itself with them.

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

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

The 'When to Use' section lists contexts (type filters, type display, reference data), but these three bullets essentially restate the same idea (get IDs to use in search filtering). No exclusions, prerequisites, or named alternative tools are given.

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 no parameters are needed and that the entire airport set is returned, but says nothing about response size, pagination, or caching — modest added value beyond the annotations.

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

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

Four markdown sections for a zero-required-parameter lookup. The 'What You Get' bullets restate the Overview (coordinates, country codes, names) and the fourth 'When to Use' bullet duplicates the first, so a substantial portion of the text is redundant rather than earning its place.

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

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

For a simple enum-style reference endpoint with no output schema, the description adequately conveys the returned fields (codes, names, coordinates, ISO-2 country codes) and that no input is needed. The one unresolved item is how it relates to its near-twin sibling, which matters for correct selection.

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

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

There is a single optional timeout parameter with 100% schema description coverage, so the schema already documents it. The description says only 'No parameters required', which is consistent with required=0 but adds no semantics beyond the structured field; 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 gives a specific verb and resource — fetch IATA airport codes with names, coordinates, and country data — and the 'What You Get' section enumerates the payload. However, it never distinguishes itself from the near-identical sibling get_data_flights_airports_iatas, so an agent cannot tell the two apart 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?

The 'When to Use' bullets give context (airport searches, location selection, reference data), but they are generic use-case restatements rather than routing rules. With a sibling like get_data_flights_airports_iatas doing essentially the same job, the absence of any when-not or alternative guidance is a meaningful gap.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond that: no parameters are required and the result is the set of supported *and enabled* languages, implying the list is dynamic. It does not mention auth requirements, but for a public reference lookup that is minor.

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

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

Front-loaded and well-sectioned, but the markdown scaffolding is heavy for a zero-argument reference lookup, and the idea that language codes feed into hotel search/detail requests is stated twice (Overview and Quick Start). It is readable but not maximally economical.

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

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

For a parameterless read-only reference tool with full annotation coverage and no output schema, the description supplies everything needed: what it returns (codes and names), when to use it, and that no input is required. 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?

There are zero parameters, which sets the baseline at 4. The description confirms 'No parameters required' and the schema is an empty object, so there is no ambiguity to resolve and nothing further the description could add.

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 all supported languages for hotel translations and content localization', and the 'What You Get' section pins down the return content (ISO 639-1 codes, English names). It does not explicitly differentiate itself from the many sibling reference tools like get_data_countries or get_data_currencies, but the resource is unmistakably distinct.

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' block gives four concrete scenarios (language switchers, localization requests, reference validation, displaying options), which is clear context for invocation. It offers no exclusions or alternative-tool routing, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: per-request pricing ($0.01), relevance ordering via Google's ranking, and smart defaults that exclude less relevant place types unless specified.

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 front-loaded, but the five-section layout is padded — 'What You Get' and 'Key Features' partly restate each other, and the Quick Start repeats the Overview. It is serviceable but not tight; several bullets could be dropped 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?

With no output schema, the description usefully compensates by describing return contents (place list, Place IDs, addresses, location types). It covers purpose, pricing, usage, and returns, leaving only minor gaps such as result limits/pagination 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 100% and the schema already documents textQuery, type, language, clientIP and sessionId in detail, so the baseline is 3. The description only echoes the textQuery example and the comma-separated type syntax; its one real addition is the 'smart defaults' note about type exclusion, which is marginal beyond the schema.

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

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

The description names a specific verb and resource ('Search for places, locations, and areas using Google Places API') and states the return type (a list of matching places). It implicitly distinguishes itself from get_data_places_placeid (detail lookup by ID) by emphasizing list search and Place ID retrieval, though it never names that sibling explicitly.

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

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

The 'When to Use' section gives four concrete scenarios (autocomplete, place selection, hotel-search boundaries, location discovery), which is clear contextual guidance. It stops short of 5 because no alternatives or exclusions are named — it never says when to prefer get_data_cities or get_data_places_placeid instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real value beyond that with per-request pricing ($0.01) and an inventory of returned data (boundaries, coordinates, metadata), which the annotations do not convey.

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

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

Markdown headers front-load the purpose and the pricing/session notes are easy to find. There is mild redundancy between 'Overview' and 'What You Get' (both repeat 'complete place details'), but structure is otherwise efficient.

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

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

With no output schema, the description usefully enumerates return contents and states the pricing model, and annotations cover the safety profile. It is nearly complete, with the only gap being no note on error behavior for an invalid Place ID.

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 placeId, language and sessionId are already documented in the schema. The description only restates that placeId goes in the URL path and adds nothing on the language or sessionId parameters, 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 opening sentence gives a specific verb and resource (get detailed information about a specific place via Place ID) and the parenthetical 'using its Place ID' implies the singular-lookup distinction from the sibling get_data_places list tool. However, it never names a sibling explicitly, so it stops short of the 5-level differentiation.

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

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

The 'When to Use' section gives four concrete scenarios (place details, boundary info, verification, display), which is clear actionable context. It does not name an alternative tool or state when this should NOT be used instead of get_data_places/search, so it misses the exclusion half of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, idempotent read. The description adds that reviews are 'authentic feedback' but doesn't cover rate limits, authentication, or the special behavior when language or getSentiment parameters are used (e.g., max 10 reviews with translation, sentiment analysis on last 1000). With annotations covering safety, this is adequate but missing key behavioral nuances.

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

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

The description is long and formatted with markdown headers, but much of the content (e.g., 'What You Get' list) repeats the same concept (ratings, reviews, comments) without adding new information. It is not front-loaded with the most critical invocation details; key parameter behaviors are buried in schema. Structure is clear but not maximally efficient.

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

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

For a read-only tool with no output schema and full schema coverage, the description covers the basic purpose but misses important behavioral aspects: the limit default of 200, maximum of 5000, the special constraint that language parameter caps results at 10, and the getSentiment behavior. These are critical for correct invocation and are not mentioned in the description. The description is adequate but leaves gaps.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description only mentions hotelId as a query parameter and doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate when 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?

States a specific verb (retrieve) and resource (guest reviews and ratings for a hotel). Clearly distinguishes from sibling tools like getExperienceTourReviews or get_data_hotel by naming the hotel guest review focus. An agent can identify this tool without ambiguity.

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

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

Provides clear usage contexts (review display, rating aggregation, trust building, decision support) but does not explicitly name alternatives like getExperienceTourReviews or exclude when not to use this tool. The guidance is helpful but not exhaustive.

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 safety profile (readOnly, idempotent, openWorld, non-destructive), so the description only needs to add behavioral context — and it does: the response structure adapts to the time range, and accuracy degrades significantly beyond one week. That accuracy caveat is genuinely useful operational information not carried by 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 and organized with headers, but it is padded: the adaptive short-term/long-term structure is stated three times (Overview, What You Get, Key Features) and the 'What You Get' bullets overlap heavily. Several sentences do not earn their place against the schema's own descriptions.

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

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

With no output schema, the description carries the burden of describing returns, and it does so (temperature, humidity, wind, precipitation, pressure, conditions, summaries) plus the accuracy caveat. Coverage is solid; only pagination/response-size behavior is unaddressed, which is minor for a forecast read.

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 latitude, longitude, startDate, endDate, and the units enum are all fully documented in the schema. The description merely restates coordinates and date range without adding format, boundary, or unit-selection 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?

Opens with a specific verb+resource ('Get weather forecasts for specific locations') and immediately scopes it by response-shape behavior (short-term vs long-term). No sibling tool covers weather, so no differentiation is required, and the intent is unmistakable.

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

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

The 'When to Use' section enumerates concrete invocation contexts (travel planning, hotel pages, trip preparation, destination info), which tells the agent what requests should trigger it. However, it names no alternatives and gives no exclusions, so it stops short of full when/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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds real behavioral context beyond them: it explains the polling-vs-webhook lifecycle and that the public response omits the providerPayment field. That is useful disclosure the annotations cannot convey.

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

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

Two short sentences, front-loaded with the primary action, no filler. Every clause carries information about when to call it or what the response contains.

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 carries the burden of hinting at returns, which it does by mentioning the voucher and the omitted providerPayment field. Combined with the lifecycle guidance, this is close to complete for a single-parameter read tool, with only the exact response shape left 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% and the single bookingId parameter is already documented as the dispatcher booking ID from POST /experiences/bookings. The description adds no parameter-level 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?

The description uses a specific verb+resource: poll booking status for an experience booking, or retrieve the voucher once confirmed. It clearly identifies the resource (experience booking) and its two operational modes. It stops short of naming a sibling it is not, e.g. getExperienceTour, so it lands at 4 rather than 5.

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

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

It states the two conditions under which the tool is used: while the booking is pending confirmation (poll) and after the webhook confirms (retrieve voucher). That is clear usage context. It does not explicitly name an alternative tool or an exclusion, so it does not reach 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 read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful return-shape context: structured itineraries appear only when the provider supplies them, locations are importance-ordered rather than itinerary order, and pricing is localized. It does not cover auth, rate limits, or pagination, keeping it below 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 markdown structure is front-loaded with an overview and scannable sections. It is somewhat longer than strictly necessary, but each section contributes useful context and there is no filler.

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

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

With no output schema, the description carries the burden of explaining return values and does so across tour profile, media, practical info, itineraries, and pricing. It also covers usage and quick-start parameter guidance. Missing only edge-case or error behavior for a full 5.

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

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

The input schema has zero properties, so the baseline for no parameters is 4. The description usefully adds that the tour id goes in the URL path and that language and currency are required query parameters, though it provides no format constraints for those values.

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 full details for a specific tour. It enumerates the returned content (description, media, inclusions, pricing context, itineraries) and distinguishes the tool from search/availability siblings by framing it as the detail view before date selection.

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 scenarios: product pages, comparison, content enrichment. It does not explicitly name when to avoid it or point to alternatives such as searchExperienceTours or getExperienceTourAvailability, but the intended context is well communicated.

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 usefully adds the return shape (dates, time slots, capacity hints), but says nothing about auth needs, rate limits, or pagination—the kind of context that would lift it above the annotation baseline.

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

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

Markdown headings make it skimmable and the purpose is front-loaded in the Overview. It is somewhat more formatted than a zero-parameter read tool needs, but no sentence is wasted.

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 appropriately carries the burden of explaining the return (available dates, slots, capacity hints). It is nearly complete; the one gap is the undocumented relationship between the referenced id/language inputs and the empty schema.

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

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

With zero declared parameters the baseline would be 4, but the description asserts a tour 'id' path parameter and a 'required language query parameter' that the input schema (empty properties) does not declare. This mismatch between prose and schema makes the parameter story ambiguous rather than illuminating.

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 available dates and time slots for a specific tour. It's clear what the tool returns. It doesn't explicitly differentiate itself from nearby siblings like getExperienceTourBookingOptions or getExperienceTour, which is the only thing keeping it from a 5.

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

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

The 'When to Use' section gives three concrete scenarios (date pickers, availability checks, booking-flow gating), which is strong context. However, it names no alternatives and gives no 'when not to use' exclusions, so an agent must infer which sibling to prefer when booking options overlap.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so safety profile is partly covered. The description adds real context beyond that: dispatcher net-to-sell markup applied in place, that `options[].price.amount` is overwritten from the lowest available slot, and an explicit warning that this is not the GYG catalog from-price. It does not cover auth needs, error behavior, or throughput limits, so it stops 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?

Headings (Overview, When to Use, What You Get, Money semantics, Quick Start) front-load the key facts and make it scannable. It is longer than necessary — pricing field paths (`totals.net` / `priceSummary.netPrice`) are repeated in three separate sections — but no section is filler.

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

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

There is no output schema, and the description compensates well by enumerating returned fields (optionId, title, bookingQuestionSchema, dateTime, isAvailable, slot-level pricing, commission) and their interpretation. What is left unresolved is the mismatch between the documented request body and the envelope-only input schema, plus any required-parameter or failure semantics.

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

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

The input schema exposes only an opaque `data` envelope (100% coverage, 0 required), so the schema alone tells an agent nothing about the real payload. The description compensates by specifying the POST body contents (`language`, `currency`, `date` as YYYY-MM-DD, `participants`) and how participants map to `ticketCategory` keys. The residual gap is that it never reconciles these fields with the single `data` wrapper property.

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 — 'Resolve priced booking options, time slots, and required guest inputs for a selected tour date and participant mix' — with the scope (date + participant mix) named explicitly. It is clearly distinguishable from sibling tools like searchExperienceTours (catalog discovery) and getExperienceTourAvailability (availability without pricing/options).

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

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

The 'When to Use' section names three concrete scenarios (option/slot pickers, live pricing display, checkout form collection) and the 'Quick Start' names the exact endpoint and body fields. It also routes downstream to prebook via `selection.price.amount`, so the agent knows both when to call it and what comes next.

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 genuinely new behavioral context: pagination via limit/offset and language-localized content. It stops short of stating auth requirements, rate limits, or what happens when a review has no localized version.

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 modest and the purpose is front-loaded under an Overview header, which is good. The markdown scaffolding (four headers for roughly six lines of substance) adds a little overhead, and the 'What You Get' section partly duplicates the Overview, but nothing is truly wasted.

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

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

With no output schema and an empty input schema, the description must describe both inputs and returns, and it does: review text/ratings/dates, pagination, and localization. Gaps remain around error behavior, authentication, and edge cases, but for a straightforward read tool the coverage is nearly sufficient.

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

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

The input schema is empty (0 properties), so the description carries the full parameter burden and does so usefully by naming the path id plus required language and currency query parameters, and the limit/offset pagination pair. That is real added value, though it does not give formats, defaults, or valid ranges, and it is inconsistent with the schema it accompanies.

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 normalized guest reviews and ratings for a specific tour.' An agent immediately knows this returns review data scoped to one tour. It does not, however, distinguish itself from the similarly-named sibling get_data_reviews or explain the boundary with searchExperienceTours and getExperienceTour.

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 contexts (review sections, trust building, decision support), but these are product-display scenarios rather than agent decision criteria. There is no explicit when-not-to-use and no named alternative tool, so selection guidance remains implied rather than actionable.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, but the description adds valuable context: Stripe transactionId/secretKey are returned as-is, GET does not create or refresh a PaymentIntent, servicesAttachable is live and not persisted, and creditLine is conditional on includeCreditBalance and account coverage.

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 is front-loaded and well-structured with scannable sections. However, the Overview and 'What You Get' sections repeat return-shape and servicesAttachable details, making it slightly verbose for a two-parameter read 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?

With no output schema, the description still conveys the return shape, persistence semantics, payment-intent behavior, and optional creditLine behavior. Annotations cover safety, so the combination is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds useful meaning by saying prebookId comes from POST /flights/prebooks and clarifying that includeCreditBalance returns a live remaining-credit snapshot when the account can cover the prebook price.

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 ('flight checkout session (prebook)') by ID, including ancillary services and live catalog scope. It distinguishes the read-only GET from POST create/attach siblings by noting that GET does not create or refresh a PaymentIntent.

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?

Has a dedicated 'When to Use' section naming four concrete scenarios: resume checkout, confirm attached ancillaries, reuse payment intent, and include credit balance. It also contrasts with POST behavior and explains where prebookId comes from.

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, non-destructive), so the description's value is in the extra constraints it discloses: confirmed bookings only, owner-scoping, sandbox/live isolation by API key, and the rule that airlinePnr and lastName are required together. Pagination behavior for a list endpoint is not addressed, which is the main remaining gap.

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

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

The heading structure is front-loaded and scannable, but for a two-parameter tool it is oversized: the PNR + last-name lookup is repeated in the Overview, When to Use, Key Features, and Quick Start sections. Several sentences restate prior content rather than earning 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: it names the response fields (status, journey, passengers, order reference, pricing) and the exact response shape (data array with one element containing a bookings array). Combined with the scoping and lookup rules, 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% and both parameters are already documented there, including the 'required together' coupling. The description restates that same coupling in prose, adding little syntactic or format detail beyond the schema, so baseline 3 applies.

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

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

The Overview states a specific verb+resource with scope: 'List confirmed flight bookings owned by the authenticated user,' plus the optional single-booking lookup. It is clear, but it never names or distinguishes itself from closely named siblings like listBookings, searchBookings, or get_bookings, so an agent must infer which list tool applies.

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 (My bookings page, PNR lookup, booking management) and the Quick Start clarifies that no params lists all while both params retrieve one booking. It lacks explicit when-not-to-use or a comparison against the sibling list/search tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety profile is covered. The description adds return content details (itinerary, passenger manifest, pricing breakdown, provider reference) not found in annotations. No auth or rate-limit info, but for a read tool with rich annotations this is adequate.

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

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

Markdown sections and bullet lists are structured but overly verbose for a single-parameter read. 'What You Get' and 'Key Features' repeat the same return content (full booking record, passenger details, provider reference), making several sentences 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?

For a simple read tool with rich annotations and no output schema, the description covers purpose, usage contexts, and return values adequately. Missing edge cases like invalid booking ID handling, but that 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 coverage is 100% and bookingId is documented as 'the unique booking identifier'. The description adds that the ID is returned from POST /flights/bookings and should be placed in the URL path, providing useful provenance and location 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 'retrieve' and resource 'complete details of a confirmed flight booking' using its unique booking ID. Distinguishes from sibling list tool get_flights_bookings and general get_bookings_bookingid by specifying 'flight booking'. An agent can easily tell what this tool does.

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

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

Provides a 'When to Use' section with four concrete scenarios (confirmation page, management, itinerary display, status checks). However, it does not explicitly name alternatives or state when not to use this tool, so routing guidance is clear but 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?

Goes well beyond the annotations: discloses the HTTP 409 / code 49007 concurrent-operation behavior, that every call hits the upstream provider (no hot polling), that refunds are potential-maximum and not granted, margin-applied pricing, and that refunds may arrive asynchronously. Annotations only cover the safety profile, so this adds substantial new operational context.

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

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

Front-loaded with Overview and sectioned headers, so it is easy to scan. However it is lengthy and repeats the 'potential maximum, not guaranteed' refund caveat across three separate sections, which is more redundancy than needed.

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, yet the description enumerates the return fields (confidence, isRefundable/isVoidable, refund/penalty, penalties[], tickets[], destination, vouchers[]) and explains the caveats around them. An agent has everything needed to call and interpret 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?

Only one parameter with 100% schema coverage, so baseline is 3. The description adds value by specifying the origin of the value ('bookingId from POST /flights/bookings in the URL path'), which the schema's terse 'unique booking identifier' does not convey.

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 (returns refund eligibility, estimated refund amounts, and penalty details for a booking) and explicitly scopes it as read-only versus the sibling POST cancellations endpoint. An agent can distinguish this quote endpoint from `post_flights_bookings_bookingid_cancellations` immediately.

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

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

Explicitly says to use this before calling `POST /flights/bookings/{bookingId}/cancellations`, and enumerates three concrete use cases (pre-cancellation review, refund estimation, eligibility check). Alternatives and the ordering condition are stated, not inferred.

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 beyond that: the bookable catalog is fetched live from the provider on every call, and booked entries echo the exact post-margin price charged at attach time.

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?

Well front-loaded with a one-line overview followed by scannable sections. It is somewhat long for a single-parameter read endpoint, and the 'Key Features' bullets partly restate the Overview and 'What You Get' sections (read-only, consistent pricing), which costs a point.

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

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

With no output schema, the description carries the burden of explaining the return shape, and it does so explicitly (groups with post-margin prices and encoded serviceIds, bookedServices, expiresAt). Nothing needed to call or interpret the response 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% for the single parameter, so the baseline is 3. The description adds value by specifying that bookingId goes in the URL path and that it originates from POST /flights/bookings, which the schema alone does not say.

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 (ancillary services for a flight booking) and precisely delineates scope as both already-booked services and the live bookable catalog. This distinguishes it from the closely named sibling get_flights_bookings_bookingid, which returns the booking itself rather than its service catalog.

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 (post-booking upsell, booking management, availability refresh) that tell an agent exactly when this endpoint applies, and the closing note rules out a use case (attaching services is not yet supported). It does not name a sibling alternative to route to, 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 declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that by enumerating the returned payload (profiles, points balance, booking history, timestamps) in the absence of an output schema. It omits pagination/volume behavior, 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?

Structure is clear and front-loaded, but it is padded for a zero-parameter list tool: the 'Quick Start' section restates what the Overview already said ('Returns all guests with their loyalty program details'), and the returned-field list is repeated in prose. Content is well organized but 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?

For a simple no-param read tool with no output schema, the description covers the call contract and describes return contents in enough detail for an agent to use the result. Missing volume/pagination expectations is the only notable gap.

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

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

There are zero parameters, so the baseline is 4. The description correctly states 'No parameters required,' which matches the empty schema and removes any ambiguity about whether filtering is possible.

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 complete list of all guests enrolled in your loyalty program') and scopes it with 'all guests', which implicitly distinguishes it from the singular get_guests_guestid sibling. It never names that sibling explicitly, so differentiation is inferred rather than stated.

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

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

A dedicated 'When to Use' section lists four concrete scenarios (guest management, points administration, customer support, reporting), giving clear context for invocation. It provides no exclusions or explicit alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that by enumerating the returned fields (name, email, phone, available/upcoming points, booking IDs, account timestamps) 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?

Front-loaded with a clear Overview, but the four markdown sections contain heavy redundancy: the 'What You Get' items restate the Overview, and 'Quick Start' repeats the parameter guidance already in the schema. It is structured but longer than the information content justifies.

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

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

With no output schema and a single fully-documented parameter, the description usefully fills the return-value gap by listing the profile fields, points, bookings, and account status. Annotations cover the safety semantics, so the tool is adequately specified, though sibling disambiguation is still 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% for the single guestId parameter, so the schema already documents it as a numeric ID. The description only restates 'provide the guest ID in the URL path' without adding format, range, or error semantics, 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: fetch a single guest by ID, plus what it returns (points, booking history, account status). However, it never distinguishes itself from the closely-named siblings get_guests_guestid_bookings, get_guests_guestid_loyalty_points, and get_guests_guestid_vouchers, which appear to expose overlapping 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 lists scenarios (customer profiles, points lookup, booking history, support tickets) but these essentially restate the purpose rather than giving discriminating conditions. No alternatives are named and no exclusions are given, so an agent cannot tell from this text when to prefer the dedicated bookings or loyalty-points siblings over this call.

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 by structured data. The description adds useful return-shape context (points per booking, cashback rates, timestamps, booking references) but says nothing about pagination, result limits, or auth scope for a read that could span a guest's entire history.

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 scaffolding is heavily redundant: 'points history', 'cashback tracking' and 'transaction details' recur across Overview, When to Use, and What You Get, and 'What You Get' largely restates the Overview sentence. Roughly half the text could be deleted 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?

With no output schema, the description appropriately sketches the returned fields, which is genuinely needed. But for a guest-scoped transactional list it omits ordering, volume, and pagination behavior, and it never resolves the naming mismatch with the loyalty_points sibling, so an agent still has open questions.

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 with 100% schema description coverage, so the schema already documents guestId fully. The description adds only the placement note ('Provide the guest ID in the URL path'), which is marginal beyond what the schema provides — baseline 3 for high coverage.

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

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

The description states a specific verb+resource ('Get all loyalty transactions for a specific guest') with concrete return content (points earned, cashback rates). However, the tool name ends in '_bookings' and a sibling 'get_guests_guestid_loyalty_points' covers nearly the same territory, yet the description never acknowledges or distinguishes itself from that sibling, leaving ambiguity about what makes this tool distinct.

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' bullets give plausible scenarios (points history, account statements, cashback tracking), which is better than nothing. But they are generic use cases rather than guidance about when to pick this over get_guests_guestid_loyalty_points or get_bookings_guest_nationality_report, and no exclusions or prerequisites are given.

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. Because there is no output schema, the 'What You Get' section adds real value by specifying the two returned balances (current and upcoming), a behavioral detail the annotations cannot convey. It omits auth requirements and error behavior for a missing guest.

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 well front-loaded, but 'What You Get' verbatim repeats the current/upcoming points already stated in the Overview, and 'Quick Start' restates the single path parameter. Roughly a third of the text is redundant for a one-parameter read call.

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 tool with full annotation coverage, the description covers what it does, what it returns, and how to call it, which compensates for the absent output schema. Only error/empty-state behavior (guest without a loyalty record) 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?

With a single parameter at 100% schema description coverage, the schema already documents guestId as the numeric guest ID. The description adds only 'in the URL path', a minor transport 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?

The Overview names a specific verb and resource (get a guest's current available points and upcoming pending points), which is far more precise than the tool name alone and clearly distinct from get_guests_guestid. It stops short of naming a sibling for comparison, so it lands at 4 rather than 5.

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

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

The 'When to Use' bullets give contexts (account pages, quick lookup, pending display, verification before redemption), but three of the four are restatements of the same read operation rather than conditions that select this tool over an alternative. No exclusions or named alternatives (e.g. the redeem endpoint) are given, 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, non-destructive and open-world, so safety is covered structurally. The description adds genuinely useful behavioral context beyond that: the shape of returned vouchers (discount type/value/currency, validity dates, usage counts, active status) and the fact that it returns ALL vouchers for the guest.

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?

Heavily structured with markdown headers and front-loaded purpose, so an agent can skim efficiently. It is a little padded ('Quick Start' largely restates the purpose), but every section is short and each earns most of its place since no output schema exists.

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

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

With no output schema and a single trivially-documented parameter, the description compensates well by enumerating the return fields and status. Nothing critical is missing for a safe read-only list call; only sibling routing/all-vouchers-vs-filtered nuance is absent.

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?

Only one parameter exists and schema coverage is 100%, so the schema already defines guestId fully. The description adds only a minor note ('provide the guest ID in the URL path'), which is baseline-level value; the 3 baseline is appropriate.

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

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

The description states a specific verb+resource ('Retrieve all vouchers available to a specific guest') with clear scoping. It is readily distinguishable from the sibling get_vouchers (all vouchers) and get_vouchers_voucherid (single voucher), since it is anchored to a guest.

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 (display, discount management, validity checking, usage tracking), which is well above implicit guidance. However, it names no alternatives or exclusions, so it falls short of the explicit when-not/routing-to-sibling standard.

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 still adds real behavioral value beyond that: fixed amounts are USD, percentages apply to the room rate (13.5 = 13.5%), and the schema is produced by an offline pipeline, so hotels without learned data return 404.

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 Overview followed by tightly scoped sections; each bullet earns its place. It is slightly longer than strictly necessary for a one-parameter read tool, but there is no filler or repetition.

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

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

With no output schema, the description carries the burden of describing the return shape and does so: each entry states inclusion in the rate, percentage vs fixed, and fixed-amount scaling. It also discloses the 404 case. Missing only a full top-level response envelope description.