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?

Annotations already mark readOnlyHint=true. The description adds that identity verification is required for security and explains the verification factors, which are behavioral prerequisites beyond what annotations convey.

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 purpose, then prerequisites, then exclusions, then follow-up tools. Every sentence adds necessary information without fluff.

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

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

For a tool with no output schema, the description adequately explains the return (confirmation number and booking summary) and all necessary context (prerequisites, security reason, related tools). No 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 coverage is 100% with descriptions. The description adds value by summarizing the three verification factor options and the condition that check_in_date is required with last_four_card, which is consistent with 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 it looks up a reservation by verifying identity and returns confirmation number and booking summary. It distinguishes from sibling tools like cancel_booking and resend_confirmation by explicitly mentioning them as follow-up actions.

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 lists prerequisites: guest full name and at least one verification factor. States 'Do not call this tool without...' and explains when to use alternatives like resend_confirmation and 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?

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds context by stating 'Sends the full confirmation to the email address on file' and the optional updated_email behavior. This clarifies the non-destructive mutation (sending an email) beyond what annotations provide. 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?

Three sentences: first states purpose and prerequisite, second describes default behavior, third covers optional parameter. Front-loaded with essential info, no redundant text. 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?

For a simple tool with 2 parameters and no output schema, the description covers behavior, prerequisite, and parameter use. It does not detail return values or error handling, but the tool's straightforward nature makes this sufficient. Additional detail on failure modes would be welcome but not necessary.

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 value by explaining that updated_email is for typoed or inaccessible original email, and reinforces the requirement for confirmation_number. It also ties the tool to the lookup_booking context, enriching parameter understanding.

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 'Resend a hotel reservation confirmation email', specifying the verb (resend) and resource (confirmation email). It also notes a prerequisite (use after verifying identity with lookup_booking), which helps distinguish it from sibling tools like book_hotel 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?

The description explicitly says 'Use after verifying the guest's identity with lookup_booking', providing a clear when-to-use. It also explains the use of updated_email for cases like a typo or inaccessible email. Although it doesn't explicitly mention when not to use, the guidance is actionable and covers common 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?

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.