travel_book_hotel

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

With no annotations, the description fully carries the behavioral transparency burden. It discloses critical details: the first call makes no booking, returns a needs_confirmation status and consentToken, requires relaying preview verbatim, and enforces a spend limit guard tied to an environment variable. This is rich, safety-relevant context beyond what the schema provides.

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 and front-loaded: the first sentence states the purpose, and the following sentences add only necessary procedural and safety details. Every sentence earns its place, and the structure helps the agent process the two-phase flow without unnecessary verbosity.

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 complex 8-parameter tool with no output schema and no annotations, the description covers the key workflow: quote prerequisite, two-phase consent, preview relay, spend limit, and consentToken re-call. It omits the return value of the second call or success handling, which would be useful, but the described flow is otherwise complete enough for safe usage.

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 the baseline is 3. The description adds contextual meaning for amount and consentToken by linking amount to the quote prerequisite and explaining the two-phase token flow, but it does not substantially elaborate on other parameters beyond their schema descriptions.

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 'Book a hotel,' a clear verb+resource statement that immediately identifies the tool's purpose. It further distinguishes itself from siblings like travel_search_hotels and travel_get_quote by framing this as the final booking step after obtaining a quote.

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 states 'Always call travel_get_quote first to obtain the amount,' providing a clear prerequisite and usage context. It thoroughly explains the two-phase consent workflow, but does not explicitly mention when not to use the tool or list alternative tools, so it stops 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.