1stay

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

Provides substantial behavioral context beyond the annotations: explains the payment handoff (guest pays hotel directly, statement shows hotel name), financial side effects (1Stay Booking Fee, loyalty points), return value type (secure checkout URL), and temporal constraints (15-minute expiry). Annotations cover the boolean safety profile (not read-only, idempotent, not destructive), while the description adds the business logic and security model.

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 tightly focused paragraphs: (1) core action + return value + security constraint, (2) financial flow details, (3) prerequisite/dependency instructions. No filler content; every sentence addresses critical booking logic, payment handling, or dependency chains.

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?

Comprehensive for a complex booking tool with external payment handoff. Compensates for the missing output schema by detailing the return value (checkout URL), covers idempotency hints (via external_reference_id in schema narrative), explains PCI compliance constraints, and describes the complete transaction lifecycle including post-booking statement details.

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 100% schema description coverage, the structured field definitions already document all 8 parameters comprehensively (including the requirement to call get_hotel_details first for rate_code). The description adds narrative workflow context but does not significantly expand on parameter meanings beyond what the schema provides, which is appropriate for this coverage level.

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 the specific verb 'Book' and resource 'hotel room', clearly distinguishing this from sibling tools like 'search_hotels' (discovery), 'get_hotel_details' (information retrieval), and 'cancel_booking' (cancellation). It further clarifies the output is a 'secure checkout URL' rather than a confirmed reservation, establishing precise scope.

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: 'Requires rate_code from get_hotel_details' and warns that it 'expires in approximately 15 minutes,' with clear remediation ('call get_hotel_details again'). Also includes critical usage constraints: 'Do not collect credit card numbers... in conversation,' specifying security boundaries that distinguish correct from incorrect 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?

Annotations cover destructive/idempotent hints, but description adds critical behavioral context: irreversibility emphasis ('cannot be undone'), financial consequence specifics (non-refundable forfeiture), side effect disclosure ('Cancellation confirmation is emailed'), and stateful workflow recommendations. 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?

Eight sentences each earning their place. Well-structured flow: purpose → warning → prerequisites → financial risk → workflow pattern → side effect. Front-loaded with action. One minor redundancy between policy awareness and forfeiture sentences keeps it from perfect 5.

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

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

Comprehensive for high-stakes destructive operation. Covers financial consequences (forfeiture), irreversibility, prerequisite verification (names/confirmation), recommended alternative workflows (rebook-then-cancel), and outcome notification (email). Adequate without 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?

Schema coverage is 100% with clear parameter descriptions already present. Description lists required parameters ('Requires guest first name...') reinforcing the schema's required array, but adds no additional semantic detail (formats, validation rules, exact matching requirements) beyond what the schema already states. Baseline 3 appropriate for high-coverage schemas.

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?

Starts with clear specific verb ('Cancel') and resource ('hotel reservation'). Unambiguously distinguishes from siblings: vs book_hotel (creation), vs get_booking/lookup_booking (retrieval), vs search_hotels (discovery). Zero ambiguity.

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

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

Exceptional guidance including: explicit prerequisites ('Requires guest first name...'), financial risk warning ('forfeits the full amount'), and specific workflow pattern for date changes ('search and book new dates first, then cancel'). Explicitly warns against canceling before securing new booking, providing clear when-not-to-use guidance.

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

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

Adds critical security context ('Developer-level lookup tool with no identity verification') beyond annotations. Describes return payload structure ('full booking details including hotel, dates...') to compensate for missing output schema. Does not contradict annotations (readOnlyHint=true aligns with 'Look up').

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 tightly written sentences: first establishes function and return values, second states security classification, third provides alternative tool guidance. No redundant 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?

Fully compensates for simple schema (1 param) and lack of output schema by detailing return values. Addresses security implications critical for a lookup tool handling booking data.

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 100% schema coverage, baseline is 3. Description reinforces the booking ID format pattern 'stk_bk_xxxx' and clarifies dual input acceptance (ID vs confirmation number), adding semantic clarity to the parameter usage.

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 specific verb 'Look up' with resource 'reservation/booking' and distinguishes from sibling 'lookup_booking' by contrasting 'developer-level' vs 'guest-facing' and identity verification requirements.

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 directs users to alternative tool 'lookup_booking' for guest-facing lookups and clearly states the security difference ('enforces identity verification' vs 'no identity verification').

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

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

Annotations declare readOnlyHint=true, but the description adds substantial business context: payment flow ('Guest pays the hotel directly'), fee structure ('1Stay Booking Fee is added at checkout'), loyalty implications ('Loyalty points eligible'), and critical domain notation about cancellation policies and room types ('Run of house', 'Suite' definitions, non-refundable rate constraints). These behavioral details are essential for user expectation management and not inferable from 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 the first sentence, followed by payment/fee context, then domain-specific room type clarifications. While multi-paragraph, every sentence delivers unique value—particularly the room type definitions and cancellation policy notes which prevent user confusion. No tautological or redundant 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?

Despite lacking an output schema, the description comprehensively lists return values (room types, live rates, amenities, cancellation policies, rate_codes) and explains the booking workflow integration. For a read-only lookup tool with safety annotations already provided, this covers necessary context including payment model specifics and loyalty program eligibility.

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% (all 5 parameters have descriptions including formats and defaults). The description provides no additional parameter constraints (e.g., checkout must be after checkin, max date range) or validation rules beyond what's in the schema. With complete schema coverage, the baseline score of 3 is appropriate since the schema carries the semantic burden.

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 active verb ('Get') and clearly identifies the resource ('rates and room details for a specific hotel'). It effectively distinguishes from search_hotels by emphasizing 'specific hotel' (requiring an ID) and from book_hotel by stating it returns data 'required by book_hotel', creating a clear workflow chain.

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 links to sibling tool book_hotel by stating it returns 'rate_codes required by book_hotel', strongly implying this is a prerequisite step. The schema description for hotel_id ('from search results') implies the preceding step. However, it lacks explicit 'when not to use' guidance or explicit sequencing instructions like 'call this after search_hotels and before book_hotel'.

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?

While annotations declare readOnlyHint=true, the description adds crucial behavioral context: it enforces identity verification before access, explicitly states it 'Does NOT return booking details in conversation', and clarifies that confirmation is sent to the email on file for privacy protection. This explains the side effects and privacy model beyond the safety 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 well-structured with clear visual hierarchy (bolding, numbered lists) and front-loaded with the core purpose. While lengthy, every section serves a necessary function for a tool handling PII and security verification; no sentences are redundant.

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

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

Given the complexity (7 parameters, identity verification, privacy constraints), the description is comprehensive. It compensates for the lack of output schema by explicitly stating what the tool does not return, explains the verification workflow, and covers security prerequisites thoroughly.

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 100% schema description coverage, the description adds semantic value by explaining the logical relationship between parameters (verification factors), noting that check-in date is required specifically with card verification, and providing use-case context for updated_email ('Use when guest typo'd their email').

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 the specific action 'Find a reservation and resend the confirmation email' and identifies the resource clearly. It distinguishes itself from sibling tools by noting 'To cancel, use cancel_booking instead' and characterizing itself as 'the guest-facing lookup tool' (implying get_booking is for agents).

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 prerequisites under 'REQUIRED — must collect ALL of the following before calling', lists specific verification factors, states 'Do NOT call this tool until...', and provides a clear alternative tool for cancellation. It also covers the failure case ('If the guest can't provide any verification factor...').

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 claims the tool performs 'Search and book', but annotations specify readOnlyHint=true, indicating a read-only operation. This directly contradicts the annotation and suggests mutation capability where none exists. While it adds valuable context about direct billing and loyalty programs, the contradiction is critical.

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?

Five concise sentences with efficient front-loading (core action first, then returns, then business model). No filler content, though 'Search and book' should be 'Search for' to avoid implying booking capability given the tool's read-only nature.

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?

Describes return values and business model (direct payment, confirmation numbers, loyalty points) despite lacking an output schema. However, the failure to clarify the search-then-book workflow and the misleading 'book' claim leaves significant gaps for a tool with complex pagination and booking-adjacent siblings.

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 100% description coverage across all 13 parameters (location, dates, cursor, radius, etc.). The description provides no additional parameter-specific guidance, but the high schema coverage means the baseline score of 3 is appropriate—no compensation needed.

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 the tool searches for hotels by location/dates and specifies return values (properties with nightly rates). However, it ambiguously claims the tool performs 'booking' ('Search and book'), which conflicts with the read-only annotation and separate 'book_hotel' sibling, creating scope confusion.

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 context about payment flow ('Guest pays the hotel directly') but offers no guidance on when to use this tool versus the sibling 'book_hotel' tool, or that actual reservations require a separate booking step. Lacks explicit when-not-to-use criteria.

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

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

Annotations declare readOnlyHint=true. Description adds behavioral context by explaining the filtering mechanism and explicitly stating the 'omit' behavior. Could add details about return format or pagination, but covers the essential interaction pattern.

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 efficient sentences with zero waste. Front-loaded with the core action, followed immediately by parameter guidance and conditional behavior. No redundancy with structured metadata.

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?

Appropriately complete for a simple read-only discovery tool with single optional parameter. Covers purpose, filtering behavior, and default behavior. No output schema exists, but for a listing tool of this simplicity, the description suffices.

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 100% coverage with baseline documentation. Description adds concrete keyword examples including 'details' (which maps to sibling get_hotel_details), providing actionable hints for valid values beyond the schema's generic examples.

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 uses specific verb 'List' with clear resource '1Stay hotel booking tools' and distinguishes itself from operational siblings (book_hotel, cancel_booking, etc.) by identifying as a discovery/meta-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?

Provides clear guidance on parameter usage—when to provide keywords ('Filter by keyword') versus when to omit ('Omit keyword to list all tools'). Lacks explicit guidance on when to use this discovery tool versus invoking sibling tools directly, preventing a 5.

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