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.