hemmabo_booking_checkout

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

The description deeply specifies side effects: 'existing bookings are never modified — checks availability and locks dates first; conflicts fail before anything is created or charged. Success creates exactly one booking and one Stripe Checkout Session on the host's account, returning paymentUrl, reservationId, and a one-time guestToken (required for status/cancel/reschedule). Only the Stripe webhook confirms the booking; unpaid bookings expire automatically.' It even covers auth (Bearer token, rate limiting). No annotation contradicts this — it's all additive.

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 a dense wall of text with no paragraph breaks, and the density makes parsing harder with typos like 'hemska_status' versus 'booking_status' and the garbled 'fallback non-VRP'. It front-loads the most important info but sacrifices readability significantly. The density is too high for a three-paragraph wall of text.

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 description covers almost every scenario: preconditions (explicit user consent), concurrency (conflicts fail before anything is created), failure/rollback, expiration (unpaid bookings expire automatically), and authentication requirements. There are no obvious missing green-flag scenarios an agent might encounter; the description appears complete.

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%, setting the baseline at 5, and the description further enriches semantics: 'channel selects which locked total is used; paymentMode changes only the handoff form, never the price' adds business logic. It also mentions 'Returns a one-time guestToken' (output) which complements 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 opening line 'Create a fallback non-VRP booking and return a host-configured checkout URL' is somewhat convoluted and grammatically tortured, but the second sentence clarifies that this is the fallback when the primary VRP flow is unavailable. The reference to get_verified_stay_offer helps disambiguate it from siblings, though the exact overloading of 'non-VRP' requires parsing.

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 'Use only after explicit user confirmation when no signed VRP direct_booking_url is available; when get_verified_stay_offer returns one, route the guest there instead' and contrasts itself with 'hemmabo_booking_create to record a pending booking without collecting payment yet'. It further provides retry and idempotency guidance: 'Not idempotent — check hemmabo_status before again.' This is a complete usage decision tree.

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