1stay

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

The description is exceptionally transparent about behavior beyond the annotations: it returns a checkout URL, accepts no payment/guest fields, states the guest pays the hotel directly, explains the merchant-of-record relationship and statement descriptor, notes automatic loyalty points, itemized fees, and a 15-minute rate-code validity with rejection of expired codes. These details substantially exceed what readOnlyHint/idempotentHint alone communicate.

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 front-loaded with the core action and key constraint: 'Book exactly one hotel room. The first 1Stay release does not support multi-room searches or reservations.' It is organized into three readable paragraphs covering scope, payment flow, and rate-code requirements. Some material (e.g., loyalty points and statement descriptor) is contextually useful but not strictly required for invocation, so it is slightly longer than minimal, yet 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?

Given the tool has 6 parameters, a complete input schema, an output schema, and rich annotations, the description fills all important gaps: what the tool returns (checkout URL), what it does not collect (payment/guest info), how payment works, the rate-code prerequisite and expiration, and booking limitations. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real semantic value for rate_code, specifying its source (get_hotel_details) and expiration behavior (approximately 15 minutes, expired codes rejected). It also clarifies that no guest identity or payment parameters exist, which prevents incorrect invocation. Other parameters like check_in/check_out and guests are already well documented in the schema, so additional description is not necessary.

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 action and resource: 'Book exactly one hotel room.' It also disambiguates scope by stating the release does not support multi-room reservations, distinguishes booking from lookups/cancellations via the secure checkout URL, and names the dependency on get_hotel_details. This leaves no ambiguity about what the tool does or how it differs 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 gives clear context for when to call this tool: it is the booking step that requires a valid rate_code from get_hotel_details, and it explains that guest identity and payment are handled on the secure checkout page, not in this call. It does not explicitly list exclusions or alternative tools (e.g., 'use cancel_booking to modify'), but the booking flow sequence and rate-code prerequisite are clear enough.

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 goes far beyond the annotations by revealing critical behavioral traits: it verifies the guest first, returns a first-party URL and policy, never cancels in conversation, provides no refund/penalty estimates, and the reservation remains active until the page reports success. This is exactly the kind of context an agent needs to avoid misleading the user. No contradiction with 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 dense with valuable information and no filler, but it is a bit long and repeats the core 'not cancelled until confirmed' point twice. Every sentence earns its place, though slight tightening could improve scannability.

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 output schema exists and annotations are present, the description covers all essential operational details: what is returned, the confirmation flow, email notification, and the non-destructive nature of the tool. An agent has everything needed to invoke it correctly and set user expectations.

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

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

The input schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds only an indirect hint that these parameters are used for guest verification ('After verifying the guest'), but no additional syntax, format, or semantic detail beyond the schema.

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

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

Clear verb+resource: creates a secure cancellation handoff for a hotel reservation. It explicitly states what the tool does, what it returns (policy + URL), and what it does NOT do (never cancels in conversation), which sharply distinguishes it from siblings like lookup_booking or book_hotel.

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 makes the use case obvious: when a guest wants to cancel, this tool initiates a handoff rather than directly cancelling. It clearly sets expectations that the guest must complete cancellation on the secure page. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough for an agent to select it appropriately.

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 detail beyond the annotations: it explains that internal booking IDs are never accepted, that anonymous access requires a verification_token from lookup_booking scoped to a single booking, and that developer-authenticated access is scoped to their own bookings. It also states that no booking data is returned without a valid token. This gives the agent a clear model of the tool's access and failure behavior.

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

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

The description is concise, front-loaded with the core purpose and key constraint, and then provides necessary authentication context. Every sentence adds useful information without redundancy or filler.

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

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

With an output schema present, the description does not need to enumerate return fields, but it still summarizes what is returned. It covers input semantics, authentication modes, scoping, and failure conditions, making the tool's behavior sufficiently complete for an agent to invoke it correctly.

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

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

Although the schema already describes both parameters, the description adds important meaning beyond the schema: it specifies that verification_token is issued by lookup_booking, is booking-scoped, and is required for anonymous access only. It also reinforces that confirmation_number is specifically the hotel confirmation from the guest's email and not an internal ID.

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: looking up a reservation by the hotel confirmation number and returning full booking details. It also draws an explicit boundary by stating that internal Stayker booking IDs are never accepted or disclosed, which differentiates it from related lookup flows.

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 this tool is for retrieving booking details using the guest's hotel confirmation number, and it gives clear context about authentication requirements and scoping. It does not explicitly say when to use an alternative sibling tool, but the purpose is specific enough that an agent can infer when to select 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?

Beyond the readOnly/openWorld/non-destructive annotations, the description discloses rich behavioral context: the guest pays the hotel directly, displayed totals include taxes and an itemized 1Stay Booking Fee, loyalty points are eligible, and non-refundable rates cannot be changed or canceled. It also clarifies domain terminology (run of house, select-service suites) that materially affects how the agent should interpret results. No contradiction with 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 front-loaded with the core purpose in sentence one and organized into three coherent blocks: purpose/outputs, payment/pricing behavior, and room-type terminology. It is longer than average, and the room-type notes are somewhat educational, but every sentence adds operational value and nothing is redundant with 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?

Given that an output schema exists, annotations cover the safety profile, and the input schema documents all six parameters at 100% coverage, the description fully covers the remaining gap: purpose, pricing behavior, fee disclosure, loyalty eligibility, and rate semantics. The only minor omission is an explicit call sequence (search first, then detail, then book), but the book_hotel linkage makes this inferable.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description reinforces the 'exactly one room' constraint that matches the rooms const=1 schema, but it does not add new parameter-level semantics beyond what the schema already documents.

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 and resource: 'Get rates and room details for exactly one room at a specific hotel.' It enumerates concrete return values (room types, live rates, amenities, cancellation policies, rate_codes) and even ties rate_codes to the book_hotel sibling, which clearly separates it from the search_hotels sibling.

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

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

The scope language ('exactly one room at a specific hotel') and the mention of 'rate_codes required by book_hotel' make the intended flow clear: query details for an already-identified hotel, then use the result to book. However, no sibling is named explicitly and there is no explicit when-not-to-use statement, so the routing to alternatives is implied rather than stated.

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

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

The annotations already declare this as a safe read operation (readOnlyHint=true, destructiveHint=false), so the description does not need to restate that. It adds valuable behavioral details: which identity factors are verified, that email is not a verification factor but is matched if supplied, and that results are returned 'in conversation'. No contradictions with 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 three tight sentences. The first sentence front-loads the core purpose and output. The second and third provide exact verification requirements and a negative case. Every sentence earns its place; no filler 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 read-only lookup tool with an output schema, this description covers everything needed to call it correctly: required identity factors, accepted verification methods, optional fields, and the negative condition. It also indicates conversational output, so the agent knows what kind of response to expect. The safety profile is already covered by annotations.

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?

Although the input schema has 100% description coverage, the tool description adds crucial cross-parameter semantics: confirmation_number is an alternative to last_four_card combined with check_in_date, and email is optional and insufficient on its own. This combination logic is not encoded in the schema field descriptions, making the description highly valuable 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 states a specific verb ('look up a reservation'), the resource ('reservation'), and adds a defining characteristic: verification of the guest's identity. It also clarifies the output type ('confirmation number and booking summary in conversation'), which distinguishes it from the sibling tools that act on bookings (book_hotel, cancel_booking, resend_confirmation) and from a generic fetch like get_booking.

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 clear context for when this tool is appropriate: the guest must provide full name plus either a confirmation number or card digits with check-in date. It explicitly states a non-sufficient condition ('a name and an email alone will not return a reservation'). However, it does not explicitly name alternative tools or say when to prefer get_booking or another sibling, so it falls short of a 5.

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

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

The description adds meaningful behavior beyond annotations: recovery requests never reveal whether a reservation matched, the email is sent only to the email on file with no recipient override, and email changes are handled externally. This gives the agent important privacy and side-effect context. No contradiction with the annotations.

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

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

The description is front-loaded with the core purpose, then gives usage alternatives, privacy behavior, and a support pointer. Every sentence adds useful information without fluff; the structure makes the tool's behavior easy to scan.

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 moderate complexity, the description covers all essential aspects: when to use each parameter combination, privacy safeguards, recipient constraints, and escalation path. With an output schema present, no critical return-value detail is missing for an agent to 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?

Schema coverage is 100%, and the description adds the crucial distinction between the two parameter sets: confirmation_number alone versus first_name, last_name, and email. It also clarifies that email is used only to find a match and that the confirmation goes to the address already on file, reinforcing and contextualizing the schema.

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

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

States a specific verb and resource: 'Resend a hotel reservation confirmation email.' It also distinguishes itself from sibling tools by explaining that the email contains the hotel confirmation number the guest can later use with lookup_booking or cancel_booking.

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

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

Gives explicit usage conditions: use the confirmation number from a successful lookup_booking call, or use the guest's full name and email when the confirmation number is unknown and the guest lacks card last four and check-in date. It also notes the recipient-restriction rule, which tells the agent when this tool is appropriate and what it cannot do.

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 mark readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond annotations: nightly rates, hotel categories, one-room limitation, direct payment, and loyalty points. No contradictions.

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

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

Two short paragraphs with the core function front-loaded. The second paragraph efficiently conveys key constraints, though a few points are redundant with schema descriptions.

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

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

Given the rich input schema, output schema, and annotations, the description is largely complete for agent decision-making. Pagination is not explicitly explained, but cursor/search_id are schema-documented and an output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'exactly one room' and '340 days' is already reflected in the schema, adding little new parameter-level 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 opens with 'Search hotels by location and dates,' a specific verb and resource, and clarifies scope (exactly one room, 340-day window). It does not explicitly differentiate from siblings like get_hotel_details, so it stops short of a 5.

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

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

Provides clear product context—first release supports one room per search, direct payment, hotel confirmation, loyalty points—which helps an agent understand constraints. It does not explicitly mention alternatives or when-not-to-use, so it lacks the explicit routing of a 5.

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

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

Annotations already declare the tool as read-only and non-destructive, covering the safety profile. The description adds the behavioral detail that omitting the keyword returns all tools and that the keyword filters by categories, which is not implied by the annotations alone.

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

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

A single sentence that front-loads the core purpose and efficiently incorporates the parameter behavior. No wasted words; every clause 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?

The tool is simple, with one optional parameter, and the output schema covers return values. Annotations handle safety, and the description covers usage semantics. There is no missing information an agent would need to select or invoke this tool correctly.

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

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

The input schema already describes the keyword parameter with examples, but the description adds the behavior when the parameter is absent ('absence of a keyword returns all tools'). This goes beyond the schema's property description and clarifies the parameter's full semantic range.

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'), making it clear this is a discovery tool. It is clearly distinguished from siblings like search_hotels (which searches hotels, not tools) and operational tools like book_hotel.

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 explains the keyword filtering behavior and the default behavior without a keyword, giving agents clear guidance on invocation. It does not explicitly state when to use this tool versus alternatives, but its purpose as a tool discovery function is self-evident relative to the sibling tools.

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