Cancun4me — Reservas de Hotel

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

Without annotations, the description fully discloses key behaviors: cancellation with potential automatic refund, and the `bloqueado: true` response when cancellation is not auto-processable. It also warns against retrying, providing critical behavioral context.

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

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

The description is concise (3 sentences) and front-loaded with the primary action. Every sentence adds value, covering the conditional behavior and agent instructions without waste.

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

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

The explanation of behavior is thorough given the tool's simplicity and lack of output schema. However, the complete omission of parameter semantics leaves a gap that could hinder correct invocation. Overall, adequate but not fully complete.

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

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

The input schema has 2 required parameters (token and order_id) with 0% description coverage. The description does not explain these parameters at all, leaving their purpose and required format entirely implicit.

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 cancels a reservation ('Cancela uma reserva'), specifying the verb and resource. Among sibling tools, it is uniquely a cancellation tool, distinguishing it from other operations like creating payments or getting info.

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

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

The description provides explicit conditions for use: automatic cancellation/refund within free period for refundable fares, and a non-retry manual process when `bloqueado: true`. It instructs the agent to avoid retrying and to contact support, making usage clear.

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

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

With no annotations provided, the description takes full responsibility. It discloses that the tool creates a payment order, returns a payment link, warns against entering card details, and explains that the booking is confirmed only after payment. It also clarifies the hospedes array requirement. This adequately informs the agent of behavioral traits.

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 relatively concise, front-loading the main purpose and output. It contains essential details in a paragraph structure. It could be slightly more structured with bullet points for clarity, but it remains effective and not overly verbose.

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 complex tool with 6 parameters, no output schema, and a payment flow, the description covers the main workflow: creation, payment link, booking confirmation, parameter constraints, and optional coupon. It does not cover error handling or failure scenarios, but these may be addressed in get_order_status. Overall, it is adequately 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?

Despite 0% schema coverage, the description adds significant meaning for two crucial parameters: it details that hospedes must be an array of {firstName, lastName} per guest totaling adults+children from the original search, and that voucher_code is optional (e.g., from get_welcome_coupon). However, token, search_id, opcao_id, and email_contato lack additional explanation beyond their names.

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

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

The description clearly states 'Cria o pedido e devolve o LINK DE PAGAMENTO (Stripe Checkout)', which specifies the verb (create), resource (payment order), and output (payment link). It distinctly differs from sibling tools like get_quote 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 provides explicit usage instructions: the host must open the payment_url on Stripe, never input card details in chat, and the booking is only confirmed after payment (to be tracked with get_order_status). It mentions optional voucher_code and hospedes format. However, it does not explicitly compare to siblings like cancel_booking.

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 burden of behavioral disclosure. It only states what the tool does (returns hotel details) but does not mention any behavioral traits such as read-only nature, authentication requirements, side effects, or rate limits. This is insufficient for a tool with no annotations.

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

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

The description is concise with two sentences, front-loaded with the primary purpose. However, it is written in Portuguese, which may hinder quick understanding for English-based agents. Still, it is efficient and avoids superfluous 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?

Given the lack of output schema and 0% schema description coverage, the description is the only source of information. It provides the essential context (using slug, language options) but does not describe the return value structure or any other details, leaving some gaps for a complete understanding.

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

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

The description adds meaning to the two parameters by mentioning the slug source and listing allowed language values ('en', 'pt', 'es'). However, it does not explain the format of the slug or provide details about default behavior. Since schema description coverage is 0%, the description partially compensates but could be more explicit.

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 that the tool returns details of a single hotel from the catalog using a slug, and it mentions that the slug is obtained from list_hotels or search_hotels. It also specifies the allowed language values. However, the description is in Portuguese, which might reduce clarity for an English-speaking agent.

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 that this tool should be used after obtaining a slug from list_hotels or search_hotels, and it provides language options. However, it does not explicitly state when not to use this tool or suggest alternatives, leaving usage context somewhat 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?

With no annotations, the description bears full burden. It discloses the type of information returned (status, expiration, messages) but does not mention any side effects, authentication requirements beyond the token, or rate limits. The read-only nature is implied but not explicit.

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

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

The description is a single sentence that efficiently conveys key return fields. However, it is slightly run-on and could be broken into structured points for easier parsing. It is concise overall.

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

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

Given the tool's simplicity (one parameter, no output schema), the description lacks explanation of the input token, which is a critical gap. The return value details are covered, but without parameter context the completeness is only moderate.

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 one required parameter 'token' with 0% description coverage. The description does not explain what the token is or how to obtain it, leaving the agent without necessary context for correct 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 that the tool returns membership status, including whether the member is active, discounts, expiration, and remaining AI messages. The name 'get_membership_status' matches the purpose and distinguishes it from sibling tools like 'join_club' (creation) and other query 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 implies usage for checking membership status, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. The context suggests it's for querying, but no direct comparison with siblings.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes what data is returned but does not state whether the tool is read-only (though 'get' implies it), what authentication is needed for the token, or any rate limits or side effects. This is a significant gap for a tool with no annotations.

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

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

The description is short with two sentences, front-loading the key return information (status list) and then the usage context. Every sentence adds value, with no unnecessary words. A minor improvement could be more structured, but it is 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 simple tool with 2 required parameters and no output schema, the description provides the essential return data and usage purpose. However, it lacks parameter details and behavioral traits, which are important for correct invocation. It is minimally complete but has clear 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 0%, and the description does not elaborate on the two required parameters ('token' and 'order_id'). It provides no additional meaning beyond their names, such as format, source, or example values. The description fails to compensate for the lack of parameter descriptions in the schema.

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

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

The description clearly states the tool returns current order status with specific possible values (aguardando_pagamento, reservado, cancelado, falhou), plus booking_id and voucher readiness. The verb 'get' matches the name, and it differentiates from siblings like 'list_my_bookings' and 'get_voucher' by being specific to a single order's status and including voucher readiness.

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

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

The description says 'Use para acompanhar se o pagamento ja confirmou a reserva' (use to track if payment has confirmed the reservation), giving a clear usage context. However, it does not explicitly state when not to use the tool or mention alternatives among siblings, such as 'create_payment' or 'cancel_booking', so guidance is partial.

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 were provided, so the description bears full responsibility. It clearly states what the tool returns (price, cancellation policy, etc.) and implies it is a read-only query (requote, not a mutation). No contradictions or negative behaviors mentioned.

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

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

The description is a single, dense sentence that front-loads the purpose and ends with usage guidance. It is efficient but could be more structured (e.g., list output fields separately) for easier parsing.

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 three required parameters with no schema descriptions and no output schema, the description fails to explain inputs. It covers output fields well but leaves parameter semantics entirely undocumented.

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 the parameters (token, opcao_id, search_id). The description adds no semantics beyond the parameter names, leaving the agent unable to understand what values to pass.

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 provides a live requote for a specific room, listing returned details (final price, cancellation policy, free cancellation deadline, room observations). It distinguishes from siblings by explicitly tying its use to pre-payment confirmation via create_payment.

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

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

The description explicitly states to call this before create_payment to confirm exact price and policy. This provides clear context for when to use it, but does not mention when not to or alternative tools for other scenarios.

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 present, so description must disclose behaviors. It reveals the output format (HTML) and the prerequisite status, but lacks details on error handling, idempotency, or side effects. Adequate but not exhaustive for a mutation-free read tool.

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

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

Two concise sentences, front-loaded with purpose. No wasted words; every sentence adds value.

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

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

For a simple read tool with no output schema, the description covers the main purpose and prerequisite, but lacks details on response format (though HTML is mentioned) and error scenarios. Missing parameter descriptions reduce completeness.

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

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

Schema coverage is 0% and the description does not explain the token or order_id parameters. Although names may be self-explanatory, the description fails to add semantic value beyond the schema, leaving a 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 clearly states it retrieves the full HTML voucher for a confirmed booking, with a specific verb ('Voucher completo') and resource. It distinguishes from siblings by mentioning the prerequisite to check status with 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?

Explicitly states when to use (only after booking status 'reservado') and directs to verify with get_order_status first, providing clear context. Also advises on how to use the output (show/describe to guest, save/print).

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. It discloses the return behavior (null if no active coupon) but lacks details on authentication, side effects, or rate limits. The description adds some behavioral context but is 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 two sentences and front-loads the purpose. Every word adds value with no extraneous content. It efficiently conveys the tool's function and return format.

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

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

Given the tool's simplicity (one param, no nested objects, no output schema), the description covers the return format and business logic. However, it does not explain the token parameter, which is a gap. Otherwise, it is mostly complete for a straightforward lookup tool.

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

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

The input schema has one required parameter 'token' with no description (0% coverage). The tool description does not explain what the token represents or any constraints, failing to compensate for the schema gap. The parameter semantics are left entirely to the agent's inference.

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

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

The description clearly states the tool retrieves a personal discount coupon (specifically the welcome coupon from first registration) if available, returning null if none. This is a specific verb-resource pair, and it distinguishes from sibling tools like get_voucher which likely handles other voucher types.

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 use for checking welcome coupon status but does not provide explicit guidance on when to use this tool versus alternatives like get_voucher, nor does it mention when not to use it. The context is implied, not explicit.

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

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

With no annotations, description fully carries burden. It discloses return of payment_url, failure on existing membership, and automatic renewal. Lacks details on success handling but sufficient for the action.

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

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

Description is concise, front-loads main action, and uses clean structure. Minor deduction for not including token explanation, but overall efficient.

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

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

Explains return value, failure condition, and references sibling tool, but missing token parameter explanation. Adequate for a one-param tool but incomplete without token context.

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 parameter 'token' is unexplained in description despite 0% schema coverage. The description adds no meaning to what the token represents or how to obtain it, a critical 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?

Description clearly states it initiates an annual club subscription with specific cost, renewal, and discount, and returns a Stripe Checkout payment URL. It is distinct from sibling tools like get_membership_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?

Explicitly advises to check membership first with get_membership_status to avoid failure, warns not to collect payment data, and indicates when to use (for sign-up) and when not (already 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 full burden. It discloses the tool is read-only and public (no personal key needed). However, it lacks details on pagination, rate limits, or any side effects, leaving some behavioral aspects opaque.

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, delivering all key points in three sentences. It front-loads the core functionality and adds usage context efficiently, though it contains a minor language mix.

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 simple tool (one optional parameter, no output schema), the description covers what it returns and when to use it. It lacks pagination details but is adequate for a basic listing 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 schema has no description for the language parameter, but the tool description explicitly lists allowed values ('en', 'pt', 'ou es'), adding critical semantic meaning. This compensates for the 0% schema 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 clearly states the tool lists a curated catalog of hotels with specific fields (name, zone, description, highlights, photos). It distinguishes itself from siblings like search_hotels by noting it does not require dates or personal keys.

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 when-to-use guidance: 'good for discovering/describing hotels before the guest chooses dates.' It also implies no need for alternatives that require dates or keys, though it doesn't name sibling tools directly.

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 full burden. It discloses the output fields (status, hotel, dates, price, cancelability) and scope (past and future), but omits information on authentication, rate limits, or data freshness. The token parameter implies authentication but is not explained.

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

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

The description is a single, concise sentence that front-loads the purpose and includes all key information about the output. Every part is necessary and 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the output well but lacks explanation of the token parameter and prerequisites. An agent may not know that the token identifies the guest, which is essential for correct invocation.

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

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

The input schema has 0% description coverage for the single required parameter 'token'. The description fails to explain what the token is or how to obtain it, leaving a critical gap for an agent to invoke the tool correctly.

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

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

The description clearly states the verb (list), resource (reservations of the guest), and scope (past and future). It differentiates from sibling tools like cancel_booking or list_hotels by focusing on the guest's own bookings.

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 does not provide guidance on when to use this tool vs alternatives. It lacks explicit context, such as suggesting it as a prerequisite for cancel_booking or other booking-related actions.

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 provided, but description fully discloses: always live (no cache), search_id is temporary and expires, prices include tier discounts and markup, and date format. No contradictions. This gives complete behavioral insight.

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?

Single, well-organized paragraph. Front-loaded with main purpose and key feature (live, never cache), then details constraints and related tools. No redundant sentences; every sentence adds essential 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?

Despite no output schema, description explains output grouping and search_id usage. Covers expiration, price composition, and required parameters. Lacks details on result structure (e.g., pagination, exact fields) but sufficient for typical usage.

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

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

Schema has 0% description coverage, so description must add meaning. It explains adults (always at least 1), children_ages as list of ages, destino_ou_hotel as optional filter, and date format. Token and language are not explained, but core parameters are well described. Substantial value added.

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

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

The description clearly states it searches for live, real-time hotel rates from Cancun4me's catalog for given dates, grouped by hotel with lowest price. This distinguishes it from sibling tools like list_hotels (no pricing) or ver_quartos (requires search_id).

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 provides when-to-use: for real-time rate search. Details requirements (at least 1 adult, date format, children_ages format) and instructs to keep search_id for subsequent tools (ver_quartos, get_quote, create_payment). Also notes expiration and retry behavior.

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 disclose behavioral traits. It describes the tool as listing available rooms, implying a read-only operation. However, it does not mention authentication requirements (token parameter) or any error conditions, which limits transparency. The description adds value by explaining the relationship to other tools but lacks detailed 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 two sentences long, front-loaded with the core purpose. Every sentence adds value: first states what it does, second explains how to use the output. No wasted words.

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

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

The tool has no output schema, so the description should cover return values. It mentions each room has an opcao_id, but does not describe other fields or structure. For a listing tool, more detail (e.g., pagination, fields) would improve completeness. The description is adequate for basic understanding 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 0%, so the description must compensate. It explains that search_id and hotel_slug come from search_hotels, adding semantic meaning. However, it does not explain the token parameter. For three parameters with no schema descriptions, the description adds partial value but leaves the token parameter undefined.

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 available apartments/room types for a specific hotel within an existing search. It identifies the resource (rooms) and action (list), and specifies that the result provides opcao_id for use in other tools, distinguishing it from siblings like search_hotels or list_hotels.

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

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

The description explicitly states when to use the tool: after a search, using search_id and hotel_slug from search_hotels. It also indicates that the output opcao_id should be used in get_quote and create_payment. While it doesn't mention when not to use it, the context is clear and provides sufficient guidance.

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