Cancun4me — Reservas de Hotel

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

No annotations are provided, so the description carries full burden. It discloses automatic refund behavior, the blocked flag condition, and the required follow-up (manual contact, no retries). This is rich, actionable behavioral disclosure beyond a mere operation definition.

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

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

The description is a single sentence, front-loaded with the action, and every clause adds value (conditions, outcome, escalation path). It is slightly long but not redundant; efficient for the information conveyed.

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 conditional behavior and lack of output schema, the description covers both main outcomes and the manual handling path. Missing parameter details and success response format, but the agent is adequately prepared for the key decision point. More detail on parameters would improve completeness.

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

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

Input schema has 0% description coverage, and the description does not mention `token` or `order_id` at all. The parameter names are somewhat self-explanatory, but no guidance is given on format, source, or required roles, so the description fails to compensate for the missing schema details.

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

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

Description clearly states 'Cancela uma reserva' (cancels a booking), a specific verb+resource action. It is distinct from all sibling tools (payments, hotel info, quotes, memberships, etc.), and no other cancellation tool exists.

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 conditional context: explains that free-period cancellations auto-refund, while non-refundable/outside-period cancellations return `bloqueado:true` and instruct the agent to escalate manually without retrying. Although no alternative tool is mentioned, none exists among siblings, so this is sufficient.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: returns a payment URL, the guest pays on Stripe, booking is only confirmed after payment, and it explains the guest count validation. It does not mention response format or error conditions, but the core behavior is well covered.

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 moderately long but well-structured: purpose first, then safety warning, then flow, then parameter details. Every sentence adds value, and the key warning is front-loaded. There is no fluff.

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

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

For a payment tool with no annotations and no output schema, the description covers the action, safety, guest count, and monitoring via get_order_status. It indicates the payment_url output but lacks explicit error handling or response details. Overall it is quite complete for the given complexity.

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

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

The schema has 0% description coverage, so the description must compensate. It explains `hospedes` in detail (one entry per guest, total must match adults+len(children_ages)) and `voucher_code` with an example. However, parameters like token, search_id, opcao_id, and email_contato are left unnamed, relying on their names for 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 description clearly states 'Cria o pedido e devolve o LINK DE PAGAMENTO (Stripe Checkout)', identifying a specific verb (cria) and resource (payment link). It distinguishes from sibling tools like get_quote and get_order_status by focusing on payment link creation.

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 context: the booking only takes effect after payment confirmation and should be tracked with get_order_status. It also warns to never ask for card details in the conversation, which is an important safety guideline. However, it doesn't explicitly contrast with all sibling tools (e.g., when to use get_quote 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds context about the scope (single hotel), the identifier source (slug from specific tools), and allowed language values. However, it does not mention side effects, error handling, or explicitly state that it is a read-only operation. The added context is helpful but not comprehensive.

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 exceptionally concise, using a single sentence plus a language specification. It front-loads the core purpose and includes only essential details. There is no redundancy or filler, making it easy for an agent to quickly grasp the tool's function.

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

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

The tool is simple (two params, no output schema), and the description adequately covers the purpose, parameter source, and language options. It clearly indicates the return is a single hotel's details. While it lacks details on error behavior or response structure, these are less critical for a basic get operation, and the description is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaningful guidance for both parameters: 'slug' is explained as coming from list_hotels or search_hotels, and 'language' is given its allowed values ('en', 'pt', 'es'). This adds value beyond the raw schema and helps the agent construct valid arguments.

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

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

The description clearly states the action ('Detalhe de UM hotel' – details of one hotel) and the resource (hotel from the catalog). It explicitly differentiates from sibling tools like list_hotels and search_hotels by emphasizing 'UM hotel' (one hotel) and using the slug as a unique identifier. This makes the tool's purpose unambiguous and distinguishes it from listing/searching tools.

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

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

The description gives explicit context on when to use the tool: when you have a slug returned by list_hotels or search_hotels. This informs the agent of the prerequisite and the typical workflow. It does not explicitly list exclusion criteria or alternatives, but the reference to sibling tools that generate the slug effectively guides proper usage.

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

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

The description discloses conditional behavior (remaining messages only if member) and explains membership benefits, which adds useful context. However, with no annotations, it does not explicitly state the operation is read-only or address token requirements or side effects, leaving some transparency gaps.

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

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

The description is a single, information-dense sentence that is front-loaded with the main purpose and then adds details. It is readable and not bloated, though the parenthetical benefit details could potentially be more succinct.

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

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

The description adequately explains the return values and conditional logic for members, which is important given no output schema. However, it omits any explanation of the required token input and does not address potential errors or edge cases, making it only moderately complete for a simple tool.

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

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

The token parameter is completely unexplained in the description. With 0% schema coverage, the description should compensate by explaining what the token is, its format, or how to obtain it, but it does not, leaving the agent without guidance for this required 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 clearly states it returns the guest's Cancun4me Club status, including membership validity, benefits, expiration, and remaining AI itinerary messages. It is specific to membership status and distinguishes from sibling tools like get_order_status or join_club.

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

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

The description implies usage for checking membership status but provides no explicit when-to-use or when-not-to-use guidance or alternatives. The context is clear enough for selecting this tool over others, but without direct wording, it remains at the implied level.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains what the tool returns (status, conditional booking_id, voucher readiness) but does not cover error handling, authorization requirements, or whether the operation is strictly read-only. The core behavior is clear, but edge cases are omitted.

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

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

The description is compact, front-loads the primary output details, and ends with a clear usage directive. No wasted words; every sentence provides useful content.

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

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

The tool is a simple read operation with two required params and no output schema, so the description appropriately explains the return values and use case. It lacks error/edge-case details, but the core context for selection and invocation is sufficiently covered.

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

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

Schema coverage is 0% and the description does not explain either parameter. While 'order_id' is fairly self-explanatory, 'token' is ambiguous (e.g., authentication token vs payment token) and the description provides no clarification or guidance beyond the schema.

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

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

Description clearly states the tool retrieves order status with specific possible values (aguardando_pagamento, reservado, cancelado, falhou), plus booking_id and voucher readiness. This distinguishes it from siblings like get_voucher or cancel_booking by focusing on payment confirmation and reservation status.

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

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

The description explicitly says to use it to track whether payment confirmed the reservation, giving clear context. It does not mention alternative tools for when other statuses are needed, but the stated use case is specific and actionable.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool 'revalidates' the final price and returns cancellation details, implying it's a read-only/verification step rather than a charging operation. It also states it should be used 'before charging', which signals no direct financial side effect. However, it omits potential behaviors like rate limits or authorization requirements, but these are not critical for a quote function.

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

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

The description is two sentences long, with the first sentence front-loading the core purpose and the second providing essential workflow context. Every sentence earns its place; there is no redundancy or extraneous detail.

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

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

The description explains the tool's purpose, usage timing, and return fields, but it leaves out parameter semantics entirely, which is a significant gap given three required parameters and no output schema. An agent would need to infer token, search_id, and opcao_id from context or other tools, making the description adequate but not complete.

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

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

The input schema lists token, search_id, and opcao_id with no descriptions, and the description provides no explanations for these parameters. It only vaguely alludes to a specific room via 'UM quarto especifico', which could map to opcao_id, but token and search_id remain unexplained. With 0% schema coverage, the description fails to compensate, making it hard to know what values to provide.

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

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

The description clearly states the tool's purpose: a live quote for one specific room, listing the specific data it returns (final price, cancellation policy, free cancellation deadline, room observations). It also distinguishes itself from the sibling tool create_payment by explicitly mentioning it should be called before charging, making its role in the workflow unambiguous.

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

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

The description provides explicit usage guidance: 'Chame isso antes de create_payment' (call this before create_payment) to confirm exact price and policy before charging. This gives a clear context for when to use the tool, though it doesn't mention when not to use it or name alternatives beyond the payment tool.

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

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

No annotations are provided, so the description carries the burden. It discloses the key precondition (status must be 'reservado') and the return format (HTML). It does not mention error behavior or that it is a read-only operation, but the verb 'get' and the purpose imply safety. This is decent given the context.

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

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

The description is concise and front-loaded, with the primary purpose in the first clause and the usage condition in the second sentence. No redundant or irrelevant information is present.

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 get tool with two parameters and no output schema, the description covers the core purpose, return format, and prerequisite condition. It lacks parameter descriptions and error behavior, but within the context of the tool's simplicity, it is reasonably complete.

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

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

The schema has 0% description coverage, and the description does not explain the 'token' or 'order_id' parameters. The names are self-explanatory to some extent, but the description does not compensate for the lack of schema descriptions, even implicitly mapping 'order_id' to the reservation. This leaves parameter semantics largely undocumented.

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

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

The description clearly states the tool returns a complete reservation voucher in HTML format for confirmed bookings. It distinguishes itself from sibling tools by focusing on the voucher and mentioning the prerequisite status, which is specific to this tool.

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

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

Explicitly states the tool only works after the reservation status is 'reserved' and advises checking with get_order_status beforehand. This gives clear when-to-use guidance and names an alternative tool for pre-checking.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It states the return value (null if no active coupon) and indicates the coupon is 'still available,' which suggests possible expiration. However, it does not mention authentication requirements, side effects, or what happens if the token is invalid, which are relevant for a tool requiring a token.

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

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

The description is two sentences, front-loaded with the key purpose, and includes a concrete return value example. Every word is useful, with no fluff or repetition of the tool name.

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

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

The tool is simple (one parameter, no output schema), and the description explains the return value and the condition for null. However, the token parameter is not addressed, and there is no mention of how to obtain or use the token, which is a significant gap for a tool that requires authentication. The description covers the basic purpose but misses a critical operational detail.

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

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

The schema has one required parameter 'token' with no description, and the description does not mention the token at all. With 0% schema description coverage, the description was expected to compensate by explaining the token's meaning or usage, but it fails to do so, leaving the parameter completely unexplained.

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 indicates the tool retrieves a personal discount coupon from the host (e.g., a welcome coupon). The tool name 'get_welcome_coupon' aligns with this, and the description adds specificity by explaining the coupon type. It distinguishes from siblings like 'get_voucher' somewhat by focusing on the welcome coupon, though it doesn't explicitly contrast 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 usage context is implied: it is for retrieving a personal discount coupon if one exists. The description states it returns null if none is active, implying a check for an available coupon. However, there is no explicit guidance on when to use this tool versus alternatives like get_voucher, nor any stated prerequisites.

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

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

With no annotations, the description carries the full burden and excels: it discloses automatic renewal, credit accrual to the next reservation, Stripe Checkout flow, and failure if already a member. This is exemplary behavioral disclosure beyond the 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 description is compact and information-dense, front-loading the core action followed by relevant caveats. Every sentence contributes valuable context, and the structure (em dashes, separate clauses) aids readability without unnecessary fluff.

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

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

For a subscription tool with financial implications, the description covers action, pricing, renewal, credit rules, payment URL, security note, and failure condition. However, the token parameter is unexplained, which is a significant gap in completeness.

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

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

The schema has a single required `token` parameter with no description, and the tool description never explains what token represents or how to obtain it. With 0% schema coverage, the description fails to add any meaning to the parameter, leaving the agent without guidance.

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

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

The description clearly states it starts the annual Cancun4me Club subscription, specifies the cost (USD 1,000/year) and key terms. It distinguishes itself from sibling tools by mentioning get_membership_status as a prerequisite check, making the purpose unambiguous.

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

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

It explicitly tells the agent to check membership status first with get_membership_status and warns never to collect payment data, instead directing to Stripe Checkout. This provides clear when-to-use and when-not-to-use guidance, including a failure condition if already a member.

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

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

With no annotations, the description carries the transparency burden. It discloses that no dates or personal key are required (no auth) and that it returns a curated catalog. It does not explain return size, pagination, or potential errors, but for a simple list, this is acceptable.

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

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

The description is a single, well-structured sentence that front-loads the action and includes all necessary details without redundancy.

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

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

The tool is simple (one optional param, no output schema). The description covers the content, use case, and language values. It does not explicitly differentiate from sibling search_hotels, but the 'no dates' comment implicitly does. Adequate.

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

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

The schema only provides a default for 'language' with no enum or description. The description adds the allowed values ('en', 'pt', or 'es') and implies localization, fully compensating for the schema's lack of detail.

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

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

The description clearly states the tool lists the curated hotel catalog with specific fields (name, zone, description, highlights, photos) and explicitly notes it does not require dates or personal key, distinguishing it from search/filtering tools.

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

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

The description provides a clear use case: discovering/describing hotels before the guest chooses dates. It mentions no dates or personal key are needed, implying when this tool is appropriate. However, it does not explicitly name sibling tools or state when not to use it.

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

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

No annotations are provided, so the description must convey safety and side effects. The word 'Lista' implies a read-only operation, and the description details the response fields, adding useful context. However, it does not explicitly state that it has no side effects, nor does it mention authentication requirements or potential errors, leaving some transparency gaps.

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

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

The description is a single, well-structured sentence that clearly conveys the tool's functionality and output fields without any unnecessary words. It is appropriately concise and front-loaded.

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

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

The description provides a good overview of the tool's behavior and output, including the cancellation field. However, the lack of explanation for the token parameter and any error/sorting/pagination behavior leaves some gaps for a list tool, especially without an output 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?

The schema has only a 'token' parameter with no description, and the description does not explain the token's purpose, format, or origin. This leaves the agent without guidance on how to obtain or use the token, making parameter semantics poor.

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

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

The description clearly states the tool lists all guest reservations (past and future) with specific fields like status, hotel, dates, price, and free cancellation availability. It uses a specific verb ('Lista') and resource ('reservas') and is distinguishable from siblings like cancel_booking or get_order_status.

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

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

The description indicates the tool is used to retrieve a complete list of reservations for the guest, which is a clear context. However, it does not explicitly mention alternatives or exclusions, such as when to use get_order_status instead for a single booking's status.

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

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

With no annotations, the description carries full burden. It discloses real-time no-cache behavior, limited-time validity of search_id, final pricing with tier discounts/markup, and Club member credit logic—far beyond what the bare schema offers.

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 dense and front-loaded with the core function, then adds necessary detail. Every sentence adds value, though the length is considerable; it could be slightly more structured, but the complexity justifies its thoroughness.

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 7-parameter tool with no annotations or output schema, the description covers all essential aspects: input semantics, output hint (search_id), time validity, downstream integration, and pricing nuances. It is a model of completeness for an AI agent to select and invoke the tool correctly.

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

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

The schema has zero descriptions, but the description explicitly explains children_ages with an example, destino_ou_hotel as optional filter, minimum adult requirement, and YYYY-MM-DD date format. It fully compensates for the schema 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 opens with a specific verb ('Busca') and resource ('tarifas AO VIVO ... nos hoteis do catalogo Cancun4me'), clearly distinguishing this rate-search tool from siblings like list_hotels or get_quote. It also states the output grouping (by hotel, lowest price) and the search_id flow, making the purpose unambiguous.

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

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

It provides clear context: always live rates, at least one adult, save search_id for downstream tools (ver_quartos, get_quote, create_payment), and date format. Though it doesn't explicitly name alternatives or exclusions, the operational workflow is clearly 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?

No annotations are provided, so the description carries the full transparency burden. It does disclose that a prior search is required (search_id/hotel_slug) and that each room has an opcao_id for later steps. However, it does not explicitly state whether it is read-only, potential errors, or any side effects.

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

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

The description is two sentences: the first front-loads the main purpose and prerequisites, the second succinctly explains the output's use. Every word contributes, with no filler or redundancy.

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

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

Given there is no output schema, the description adequately hints at the return data by mentioning opcao_id and its role in subsequent tools. The tool has only 3 parameters and a simple list operation, so the description covers the critical workflow context 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?

With 0% schema description coverage, the description compensates by explaining the meaning and source of search_id and hotel_slug (returned by search_hotels). Token is not clarified, but it is a common auth parameter. This adds meaningful semantic value for two of the three parameters.

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

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

The description clearly states the verb 'Lista' (lists) and the resource 'apartamentos/tipos de quarto' for a single hotel within an existing search. It distinguishes itself from siblings like search_hotels and list_hotels by specifying it operates on a previous search and returns room 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 description explicitly says to use the search_id and hotel_slug returned by search_hotels, and directs the resulting opcao_id to get_quote and create_payment. This provides clear when-to-use context and workflow sequencing, though it doesn't explicitly state when not to use it or name alternatives.

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