1stay

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

The description goes far beyond annotations by disclosing that payment happens via a separate checkout URL, the guest pays the hotel directly, the statement shows the hotel name, a 1Stay Booking Fee is added, and rate codes expire in ~15 minutes. No contradiction exists with the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

The description is compact and front-loaded with the core action and return value. All subsequent sentences earn their place: payment handling, fee, loyalty, and rate_code expiry. No fluff or repetition of schema details.

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

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

For a booking tool with no output schema, the description provides a complete operational picture: what the tool returns (checkout URL), how payment works, the fee, loyalty behavior, and the critical rate_code dependency. This is sufficient for an agent to invoke correctly and handle follow-up actions.

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

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

Schema coverage is 100% with per-parameter descriptions, so baseline is 3. The description adds meaningful value by explaining the rate_code must come from get_hotel_details and expires, and by specifying hotel_id provenance from search/details. This exceeds schema-only guidance but does not fully elaborate on every parameter.

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

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

The description uses a specific verb ('book') and resource ('hotel room') and clearly states the output ('returns a secure checkout URL'). It distinguishes book_hotel from sibling tools like search_hotels and get_hotel_details by focusing on the booking action and payment flow.

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 clearly requires a prerequisite call to get_hotel_details for a valid rate_code and instructs to call it again if expired. It also gives a boundary: do not collect payment info. However, it does not explicitly contrast with cancel_booking/get_booking or state when not to use this tool, though the purpose is clear.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses the two-step nature (nothing is cancelled in the first call), token single-use and 10-minute expiry, non-refundable rate forfeiture, and email confirmation. This enriches the bare destructiveHint and readOnlyHint flags with concrete operational details.

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 structured into clear paragraphs/calls, with each sentence contributing necessary information: the two-step flow, token expiry, non-refundable warning, and confirmation email. No filler or redundant phrasing; it is as concise as a complex two-step process allows.

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 complexity and lack of output schema, the description fully explains the process, token behavior, refund/penalty terms, and follow-up action, leaving no critical gaps. It is complete enough for an agent to execute the cancellation correctly without further clarification.

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

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

The input schema already provides detailed descriptions for all parameters, including the cancellation_token semantics (leave empty first, then use token). The description's narrative reinforces this but does not add significant new meaning beyond the schema. Therefore, 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 opens with a clear, specific verb and resource: 'Cancel a hotel reservation.' It goes beyond a simple restatement by detailing the two-step, server-confirmed action, which distinguishes it from sibling tools like book_hotel and get_booking. The scope is well-defined.

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 step-by-step usage instructions: first call with guest details and empty token to preview terms, then second call with the token to execute. It also advises getting guest confirmation before the second call and warns about non-refundable rates. This is directly actionable guidance, clearly stating when and how to use the tool, though it does not name alternative tools or 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=true and destructiveHint=false, and the description adds meaningful behavioral context: without a valid token the tool returns no booking data, and developer access is scoped to their own bookings. This goes beyond the annotation-provided safety profile, though it does not cover edge cases like error formats or partial results.

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

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

Two sentences front-load the core purpose and return value, followed by a compact authentication note. Every sentence is informative and necessary, with no filler or repetition of structured field names from the schema.

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

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

For a read-only lookup tool with no output schema, the description specifies return contents (hotel, dates, guest info, rate, status), the required token flow, and access scoping. This is sufficient for an agent to select and correctly invoke the tool without needing additional clarification.

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

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

The schema covers both parameters fully (100% coverage) with clear descriptions for booking_id and verification_token. The tool description largely restates the same information about the token flow and booking identifier, reinforcing but not significantly adding beyond what the schema already provides.

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

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

The description uses specific verb 'Look up' and resource 'reservation by booking ID or hotel confirmation number', clearly distinguishing it from siblings like lookup_booking (identity verification) and get_hotel_details (hotel info). It also states exactly what is returned: full booking details including hotel, dates, guest info, rate, and 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 the prerequisite workflow: guest-facing anonymous callers must call lookup_booking first to obtain a verification_token, and developers with their own API key can skip it. This clearly explains when to use this tool and identifies the preceding/alternative tool, making the usage context unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no safety contradiction exists. The description adds substantial behavioral context beyond annotations: guest pays hotel directly, a 1Stay Booking Fee applies, loyalty point eligibility, room-type interpretations (run of house, suites), and non-refundable rate restrictions. These are non-obvious behavioral traits that aid invocation and post-invocation expectations.

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

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

The description is efficiently structured: a clear first sentence states purpose and returns, followed by two short paragraphs adding payment context and room-type clarifications. Every sentence adds value with no redundancy. It is front-loaded with the core action and output.

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, the description sufficiently explains return values (room types, live rates, amenities, cancellation policies, rate_codes) and critical business rules (payment, fees, non-refundable implications). Combined with complete schema documentation and annotations, the description is fully adequate for an agent to select and invoke this tool.

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

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

Schema description coverage is 100%, with detailed field explanations (e.g., accessible behavior). The tool description itself adds minimal parameter semantics beyond the schema, but the schema already carries the full burden. Baseline 3 is appropriate since the description does not compensate for any gap, but none exists.

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+resource: "Get rates and room details for a specific hotel." It enumerates concrete return items (room types, live rates, amenities, cancellation policies, rate_codes) and explicitly ties to book_hotel, distinguishing it from search_hotels (browsing) and book_hotel (booking). This fully differentiates it from siblings.

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

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

The description implies usage context by stating that the returned rate_codes are required by book_hotel, making this a precursor to booking. It also clarifies payment and fee details. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of an explicit when/when-not guideline.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: verification factors are mandatory, email is not sufficient, and the reason is security. It also clarifies the return value ('confirmation number and booking summary') which is not covered by annotations. No contradiction found.

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 organized with a clear summary, a numbered list of prerequisites, and a warning. Every sentence contributes necessary information without fluff. The front-loaded first sentence immediately states the tool's purpose.

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

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

Given the tool's moderate complexity, the description covers purpose, return value, required parameters, parameter combinations, negative guidance (email not sufficient), security rationale, and related tools. No output schema exists, but the return value is clearly stated. The description is self-sufficient.

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

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

Schema coverage is 100%, but the description goes beyond by explaining the combinatorial logic: confirmation_number OR last_four_card+check_in_date, and that email alone is insufficient. This adds significant meaning to parameter relationships that the schema 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?

The description clearly states the tool's function: 'Look up a reservation by verifying the guest's identity' and that it returns the confirmation number and booking summary. It distinguishes itself from resend_confirmation and cancel_booking, but does not differentiate from the sibling tool get_booking, which could be confused. Otherwise, the verb and resource are specific.

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 preconditions, listing required factors (full name plus one of two verification methods) and what is not acceptable (email alone). It also names alternatives for resend and cancel. However, it does not mention when to use get_booking instead, leaving a gap in sibling differentiation.

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

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

Annotations are sparse (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description adds critical behavioral details: the email is always sent to the booking record address, cannot be redirected, and the fallback for inaccessible inboxes. This goes well beyond the structured data.

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

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

Three sentences, front-loaded with the core purpose. Each sentence serves a distinct function: purpose, prerequisite, and behavioral constraint/alternative. 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?

Given the tool's simplicity (one parameter, no output schema), the description fully covers the action, the required precondition, the inherent limitation, and the fallback path, making it complete and context-rich.

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 the only parameter (confirmation_number) clearly described as 'Hotel confirmation number.' The description adds no additional param-level semantics, matching the baseline for full 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 action ('Resend a hotel reservation confirmation email') with a specific verb and resource. It distinguishes itself from siblings like book_hotel and lookup_booking by focusing on the resend operation and its prerequisite.

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

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

It explicitly says 'Use after verifying the guest's identity with lookup_booking,' providing a clear when-to-use context. It also gives an alternative (direct to support) for guests without inbox access, clarifying when not to use the tool.

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

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

The description directly contradicts the annotations: it says 'Search and book hotels' while readOnlyHint is true, implying the tool can perform write operations (bookings). The later sentences about 'Guest pays the hotel directly' and 'Hotel's own confirmation number' may suggest the tool facilitates booking, further confusing the read-only nature. This is a clear annotation contradiction, and no other behavioral traits are disclosed beyond what annotations already state, so a score of 1 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?

The description is brief (about 40 words) and front-loads the purpose, but the final three sentences are incomplete fragments ('Hotel's own confirmation number.') that feel disjointed. It's concise, but the lack of proper structure and the confusing 'book' mention reduce clarity. It's not egregiously long, but the fragments and mixed messages prevent a higher score.

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 has 13 parameters, no output schema, and a read-only annotation, the description is not comprehensive. It fails to explain that the tool does not actually book hotels (contradicting the first sentence), doesn't mention pagination or search_id/cursor usage, and gives no context about chain_code filters or max_results behavior. The direct-payment detail is useful but not enough to make up for the missing clarification and usage guidance.

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

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

The input schema has 100% description coverage for all 13 parameters, so the schema already explains parameters like check_in, location, and chain_code in detail. The description only vaguely mentions 'location and dates' and doesn't add any new semantic detail beyond what the schema provides. With high schema coverage, the baseline is 3, and the description does not go beyond that.

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

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

The description states the main action as 'Search and book hotels' and mentions returning available properties with nightly rates, which clearly indicates the search function. However, the inclusion of 'book' is misleading because the tool is read-only (readOnlyHint=true) and there is a separate sibling tool 'book_hotel'. The description also doesn't distinguish itself from adjacent tools like 'get_hotel_details' or 'search_tools', so it's not a 4 or 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 description gives no explicit guidance on when to use this tool versus alternatives. It implies that you use it to search hotels by location and dates, but it doesn't state when not to use it (e.g., when you need to book, use book_hotel) or mention any alternatives. There's no 'when to use' or 'instead of' language, so the guidance is minimal.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds keyword filtering behavior, which is useful, but doesn't add further context such as return format or any edge cases. With annotations covering the core safety traits, a 3 is appropriate.

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

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

Two short sentences that are front-loaded with the purpose, followed by filtering instructions. No wasted words, every sentence earns its place.

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

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

This is a simple tool with one optional parameter and no output schema. The description fully covers both usage modes (with and without keyword), and clearly conveys the tool's role relative to its siblings. Nothing essential is missing.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description adds value by giving concrete example keywords ('search, book, cancel, details') and clarifying that omitting the keyword lists all tools, which goes beyond the schema's generic description.

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

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

The description uses a specific verb ('List') and resource ('available 1Stay hotel booking tools'), clearly distinguishing this meta-tool from the sibling booking tools it enumerates. It states exactly what the tool does in one concise sentence.

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: filter by keyword with examples (search, book, cancel, details) or omit keyword to list all tools. It doesn't explicitly state when not to use this tool, but as a discovery tool, the alternatives are implicitly the tools it lists, so the guidance is sufficient.

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