HemmaBo Host Booking Engine

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

Annotations already mark the tool read-only and idempotent, and the description reinforces this with concrete prohibitions: 'must not lock a quote, create a booking, collect guest details, or start checkout.' It also adds meaningful behavioral detail such as night count rather than dates driving the signed price, and language never affecting price or availability. 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?

The description is longer than average but densely informative and well front-loaded, with the core action stated first and usage guidance following. Minor redundancy exists in repeating the language guidance and the checkIn/checkOut ordering, but given the complexity and the need to disambiguate from many siblings, the length is justified.

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 is complete for an agent to select and invoke the tool correctly: it specifies when to call it, how the parameters interrelate, what side effects are forbidden, and how it differs from fallback booking tools. An output schema exists, so omitting return-value details is acceptable.

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?

Although schema coverage is 100%, the description goes well beyond the schema by explaining that the parameters 'work as a set,' requiring the same domain and dates used at search, and by clarifying that the night count—not the dates—determines pricing. It also adds crucial guidance for the optional language parameter: always pass the guest's conversation language, since it only affects formatting.

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 verb-resource pair: 'Fetch, verify, and render a live host-domain signed VRP stay offer for exact dates and guest count.' It further sharpens the purpose by naming the JWS verification mechanism, which clearly separates this tool from the search and booking 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?

Usage context is explicit: call it after hemmabo_search_properties or verify_vacation_rental_node, and always before quoting a final price or booking link. It also states the fallback path to hemmabo_booking_negotiate/hemmabo_booking_checkout, with conditions including 'only when this call returns no signed offer' and explicit user confirmation.

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 signal destructive and idempotent, but the description goes further: repeat cancels are refused and never trigger a second refund, Stripe refunds follow the host policy, Bearer auth is required, and the call is rate-limited per token. No contradiction with annotations exists.

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 dense but well-organized: core action first, followed by exclusions, alternatives, prereqs, behavior, and parameter clarification. Every clause earns its place; the only minor cost is length, but that length is justified for a destructive financial tool.

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 destructive, refund-triggering tool with auth constraints and token pairing, the description covers when to use it, prerequisites, behavioral idempotency, parameter provenance, and required credentials. The presence of an output schema means return-value documentation is not the description's burden; nothing needed for correct invocation 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 the baseline is 3, yet the description adds meaningful guidance beyond the schema: reservationId must be a booking UUID from specific sibling tools and never a propertyId, guestToken must match the exact token issued at creation and is not substitutable by a Bearer token, and an omitted reason shows 'Cancelled via MCP' to the host.

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 verb-resource pair — 'Cancel a confirmed booking' — and adds the refund behavior. It also distinguishes itself from hemmabo_booking_reschedule by naming the condition that selects each tool, making sibling differentiation explicit.

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?

It gives explicit when-to-use ('guest explicitly requests cancellation'), when-not-to-use ('pending/unpaid bookings'), and a named alternative ('hemmabo_booking_reschedule'). It also provides a prerequisite step ('read cancellationPolicy from hemmabo_booking_status') and auth/rate-limit expectations, leaving nothing to inference.

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 richly complements the annotations (readOnlyHint=false, idempotentHint=false) with concrete behavior: 'existing bookings are never modified — availability is checked and dates briefly locked first; conflicts fail before anything is created or charged.' It also discloses lifecycle details (webhook confirmation, auto-expiry, one-time guestToken) and auth/rate-limit requirements, going well beyond what annotations alone convey. No contradiction found.

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 structured into a focused intro, behavior paragraph, and param notes. Every sentence carries information (auth, idempotency, fallback logic) without redundancy. It is moderately long but economically written, with the core purpose and usage up front. Slightly dense, but not padded.

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 10-param mutation tool with output schema and annotations present, the description covers all necessary context: purpose, fallback routing, behavior (locking, conflict handling), return values (paymentUrl, reservationId, guestToken), confirmation mechanism (webhook), expiry, idempotency, auth, and rate limits. Nothing an agent needs to decide or invoke 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 the schema already documents parameters. The description adds meaningful context for key params: quoteId (15-min validity, 'pass quoteId only for the exact propertyId/dates/guests locked'), channel (selects which locked total is used), paymentMode (changes only the handoff form, never price), and propertyId (guidance to pass exact UUID, never a name/URL). This enriches semantics beyond schema descriptions, though not every parameter gets extra treatment.

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 verb+resource: 'Create a fallback non-VRP booking and return a host-configured Stripe checkout URL.' It explicitly contrasts with sibling tools, naming get_verified_stay_offer and hemmabo_booking_create as alternatives, making the purpose unambiguous and distinct.

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 explicit when-to-use: 'Use only after explicit user confirmation when no signed VRP direct_booking_url is available' and directs to alternatives ('when get_verified_stay_offer returns one, route the guest there instead'). Also gives a retry caveat ('Not idempotent — check hemmabo_booking_status before retrying'), covering both selection and operational 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?

Discloses that availability is checked first and conflicts fail before writing, that the call is not idempotent (matching idempotentHint=false), and that it requires Authorization and is rate-limited. It also notes exact write behavior and returns a one-time guestToken. This goes well beyond the annotations, providing deep operational context without contradicting them.

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?

Despite length, every sentence adds essential information: purpose, usage conditions, auth, behavior, idempotency, pricing, required fields, and return values. It is logically ordered and front-loads the most critical scoping and usage constraints.

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 all operational aspects an agent would need: when to use, auth/rate limits, availability pre-check, idempotency handling, pricing behavior, required/optional parameters, and return values. Given the tool's complexity and the existence of an output schema, nothing critical 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 parameters are already documented. The description adds value by clarifying there is no price or quoteId parameter, that the node prices the stay itself, and that guestName and guestEmail are required while guestPhone is optional. It also explains how the booking is identified, which is not explicit in 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 the tool creates a pending direct booking without online payment for non-VRP fallback deployments. It distinguishes this from signed VRP offers by explicitly naming the alternative, making the purpose unmistakable and differentiated from sibling tools.

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 says to use only after user confirmation, with a propertyId from search, and only when no signed VRP direct_booking_url is available. It also tells the agent to route signed VRP offers to the host-domain URL instead, and advises checking status before retrying on timeout. This is clear when/when-not guidance with an alternative.

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?

Despite sparse annotations, the description discloses auth requirements, rate limiting, non-idempotence, snapshot creation, fixed validUntil, refusal on unavailable calendar dates, and the dual public/direct total freeze. It also clarifies redemption constraints and downstream checkout behavior, going far beyond what annotations provide.

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?

Although long, every sentence adds a distinct operational fact and there is no filler. The critical scoping correction is front-loaded, followed by usage conditions, side effects, and redemption constraints in logical order.

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 non-idempotent, auth-required, time-boxed quote tool, the description covers when to call it, when never to call it, prerequisites, side effects, expiry behavior, exact-match requirements, and downstream checkout interaction. Since an output schema exists, not explaining return values is acceptable.

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 descriptions already cover all four parameters, so the baseline is 3. The description adds value by explaining that the quote is bound to the exact propertyId/checkIn/checkOut/guests combination and that night count plus guest count jointly select the price tier.

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 'PRICE LOCK, not negotiation' explicitly corrects the misleading tool name and defines the operation as freezing the host-source price for 15 minutes. It identifies the exact resource and distinguishes this tool from checkout and verified-offer 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?

It explicitly says 'Use it only in the non-VRP fallback checkout flow, when no signed direct_booking_url is available and the user explicitly asks to lock a price' and gives a precise never-use list. It also names get_verified_stay_offer as the alternative for verified-offer display, leaving no judgment call.

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 declare the tool read-only and idempotent, and the description adds meaningful behavioral context: quotes are invalid without prior availability, prices are integers in local currency, and the price tier depends on the combination of night count and party size. It also discloses that changing any pricing input requires a re-quote, which is valuable beyond the structured metadata.

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 dense but every sentence earns its place: purpose, usage timing, return content, currency format, and re-quoting behavior. It front-loads the core purpose and keeps critical caveats early, without repeating schema details verbatim.

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 rich annotations, fully described input schema, and presence of an output schema, the description is complete for an agent to select and invoke this tool correctly. It clarifies the booking-flow position, return highlights, currency convention, and the dependency on prior availability — nothing essential 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 the baseline is 3. The description adds extra meaning by explaining that propertyId, checkIn/checkOut, and guests collectively determine the price tier and that changing any of them invalidates the quote. This goes beyond what the input schema states about each parameter individually.

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 a specific verb ('Get'), a precise resource ('detailed pricing quote'), and the key inputs (property, dates, guest count). It also positions the tool within the booking flow as the step between availability confirmation and booking, distinguishing it from siblings like hemmabo_search_availability and hemmabo_booking_create.

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 explicit when-to-use guidance ('Use this tool after confirming availability') and a direct prohibition ('Do NOT use before checking availability'). It also explains the consequence of misuse ('the quote may be invalid'), which helps an agent decide the correct order of operations among the sibling tools.

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 annotations only declare destructiveHint=true and readOnlyHint=false, but the description goes much further. It discloses that original dates are released, the original price no longer applies, the booking is updated in place and never recreated, and the price difference is charged or refunded via Stripe. It also notes rate limiting and the need for a guest token even with a valid Bearer token. This is precisely the behavioral context an agent needs.

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 long, but every sentence earns its place: purpose, usage conditions, destructive consequences, authentication caveat, and parameter workflow are all covered. It is front-loaded with the core purpose and then deepens into operational detail. It could be slightly tighter, but the density is justifiable for a destructive write operation.

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 5 parameters, destructive side effects, dual-auth requirements (Bearer + guestToken), and Stripe financial impact, the description covers all essential decision points: when to use, when to avoid, prerequisites, behavioral consequences, and parameter semantics. An output schema exists, so return-value documentation is not required. Nothing critical 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%, and the schema descriptions are already detailed, so the baseline is 3. The description adds meaning beyond the schema by explaining the re-pricing model ('the new night count re-prices the stay exactly like a fresh quote') and the relationship between reservationId and the new stay parameters. This elevates it slightly above the baseline.

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 verb+resource: 'Reschedule a confirmed or pending booking to new dates with automatic repricing and Stripe charge/refund.' It clearly names the action, target resource, and side effects. It also distinguishes itself from the cancel sibling, so an agent can tell which tool to use without inspecting other definitions.

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 when to use the tool ('when the guest wants to change dates on an existing booking'), when not to use it ('if cancelled or if a protocol compatibility client reports completed'), and names the alternative (hemmabo_booking_cancel) for the different use case. It also instructs the agent to check hemmabo_booking_status first, which is clear operational 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?

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint, so the baseline is lower, but the description adds substantial context: read-only against the database, safe to poll after a checkout timeout, returns guest PII, requires Bearer token auth, and is rate-limited per token. It even explains the security behavior of a mismatched reservationId/guestToken pair. 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?

Despite its length, every sentence earns its place. The definition is front-loaded with purpose, then usage, exclusions, auth, safety, and parameter semantics, with no redundant or filler content. The density is justified by the tool's security-sensitive nature and the need to distinguish it from many siblings.

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 the full operational picture: purpose, when to use, when not to use, alternatives, authentication, rate limits, read-only safety, PII exposure, parameter provenance, and failure semantics. Since an output schema exists, the absence of return-format details is not a gap. Nothing an agent needs for correct invocation 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%, giving a baseline of 3, but the description adds meaning beyond the schema: reservationId is the booking UUID returned by hemmabo_booking_checkout or hemmabo_booking_create and 'never a propertyId,' while guestToken is 'the secret issued with that same booking.' It also states that a mismatched pair reveals nothing, which is critical security semantics not present in 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 sentence precisely states the verb, resource, and identifier: 'Retrieve current status and full details of an existing booking by reservationId.' It also explicitly distinguishes the tool from siblings by naming the tools not to use (hemmabo_search_properties, hemmabo_search_availability, hemmabo_booking_quote), leaving no ambiguity about 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?

The description gives concrete when-to-use guidance: 'Use to confirm checkout/create succeeded or before cancel/reschedule.' It also provides explicit exclusions and alternatives, saying 'Do NOT use for property discovery, availability, or pricing — use hemmabo_search_properties, hemmabo_search_availability, or hemmabo_booking_quote for those.' This leaves no inference required.

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 declare readOnly/idempotent/non-destructive, and the description amplifies this by listing concrete side effects it does NOT have (no account creation, domain purchase, Stripe config, Supabase writes, or booking-site provisioning) and states that no data is stored server-side. It also discloses the output substance: the URL, what the host gets, and what to prepare.

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?

Each sentence adds a distinct fact—purpose, audience exclusion, readiness-check routing, read-only side-effect exclusions, output components, and prefill semantics. The key action is front-loaded in the first sentence, and the longer parameter caveat is safely placed last.

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 tool has an output schema, so return-value detail is already structured, and the description covers audience, timing, alternatives, side-effect profile, and parameter semantics. An agent has everything needed to decide whether to invoke it and what to pass, with no missing prerequisites.

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?

Every parameter is already documented in the schema (100% coverage), and the description adds a crucial group-level semantic: all six are optional prefill that never changes the destination URL; blanks are omitted and nothing is stored. This tells the agent the parameters are cosmetic prefill, which is not inferable from individual 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 names a specific operation—'Return a safe ... onboarding handoff URL'—with the audience ('host who wants their own booking website') and immediately contrasts with hemmabo_search_properties and hemmabo_host_readiness_check, so the tool is unambiguous against its 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?

It gives explicit invocation conditions: use 'after explaining the fit or when the host asks to start'; if still evaluating, run hemmabo_host_readiness_check first because it returns the same URL in next_step; guests should use hemmabo_search_properties. This is as explicit as when/when-not guidance gets.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description consistently reinforces the read-only nature ('Does not create an account, buy a domain, configure Stripe, store host data, or provision a website'). It adds behavioral detail beyond the annotations: the safe onboarding next step, the omission semantics of wants* booleans ('count unless explicitly false — omitting them never lowers the verdict'), and what happens with no inputs ('summary is generic'). 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?

The description is a single dense paragraph that front-loads the verb, scope, and user audience, then proceeds to exclusions, return contents, and parameter semantics. It is longer than the typical ideal, but every clause earns its place—there is little redundancy and it packs meaningful routing and behavior detail. A bulleted or two-paragraph structure would improve scannability, but the density is justified.

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 11 optional parameters, no required inputs, an output schema, and strong annotations, the description covers all decision-relevant aspects: who should use it, what it returns, what it does NOT do, what input changes the result, what happens with no input, and which sibling to invoke next. The output schema covers return values, so no return-format detail is needed. Nothing an agent needs to call it 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 the baseline is 3, but the description adds valuable cross-parameter semantics above the schema: it groups all 11 params into 'five inputs that sharpen the fit verdict' vs 'only prefill the onboarding URL', explains that wants* booleans count unless explicitly false, and clarifies that omitting them never lowers the verdict. That is genuinely additive meaning, not schema repetition, though it doesn't enumerate every parameter by name.

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 begins with a crisp verb+object ('Read-only fit check') and names the exact target user (vacation-rental host) and product context (HemmaBo for their own booking website/booking engine). It explicitly contrasts with the guest-facing sibling hemmabo_search_properties, so an agent can disambiguate the tool without reading schemas. It also names the follow-up sibling (hemmabo_host_onboarding_link).

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 states when to use ('when the user is a host or property owner'), when not to use ('not a guest booking a stay; guests should use hemmabo_search_properties instead'), and what the next tool is when the host is ready ('follow up with hemmabo_host_onboarding_link'). It also clarifies which inputs sharpen the verdict versus which only prefill the onboarding URL, giving an agent actionable routing 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?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds valuable context beyond those: anonymous access with no Bearer token, rate limiting, no holds or date reservations, fail-closed behavior on stale calendar sync, and alignment with the host node's availability API. 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?

The description is dense but front-loaded with the core purpose in the first sentence and every subsequent sentence earning its place by covering usage, exclusions, behavior, failure modes, or parameter semantics. Despite its length, it avoids redundancy and reads as a coherent operational guide.

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 that an output schema exists, return-value details need not be spelled out. The description covers when to use, when not to use, authentication, rate-limits, side-effect freedom, parameter-conditional behavior, failure modes, and reliability expectations. Nothing essential for correct invocation 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% with per-parameter descriptions, and the description adds meaning beyond the schema: omitting guests checks dates only, providing guests gates capacity and prices alternative windows, and min_nights_violation guidance distinguishes extending the stay from shifting dates. It also warns to pass the exact property UUID, not a name or URL.

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 verb and resource: 'Check whether a specific property is available for the requested dates.' It clearly differentiates from siblings by explicitly routing general browsing to hemmabo_search_properties and positioning availability checks before quote creation.

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?

It states exactly when to use the tool: after the user selects a property from hemmabo_search_properties to confirm availability before a quote. It also gives an explicit exclusion: 'Do NOT use for general browsing — use hemmabo_search_properties instead,' leaving no ambiguity about alternatives.

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 and idempotentHint=true, but the description adds significant behavioral nuance: 'Discovery only', 'never quote a final price', 'Capacity misses are excluded', and 'date-unavailable matches return separately in unavailableMatches with up to three alternative windows'. These details are not present in annotations and help set agent expectations.

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 dense but efficient—every sentence carries purpose, front-loaded with purpose and usage. Slightly verbose with overlapping statements ('Discovery only' and 'never quote a final price'), but it remains focused and scannable.

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?

Covers purpose, usage, exclusions, workflow, return content, and parameter interaction. With an output schema and read-only annotations already present, the description provides everything an agent needs to select and invoke this tool correctly.

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%, but the description enriches semantics: it explains how params combine into a single filter, clarifies region vs country matching behavior ('region matches broadly... while country matches the country field alone'), and documents the effect of omitting both ('search spans every published property'). This goes well beyond the 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?

States a specific verb and resource: 'Search available vacation rental properties by location and travel dates.' It also differentiates from siblings by defining the exact use case ('find or browse places to stay') and explicitly routing away when a propertyId or host domain already exists.

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 explicit when-to-use ('Use when the user wants to find or browse places to stay'), when-not-to-use ('Do NOT use when the user already has a propertyId or host domain'), and a workflow directive (call get_verified_stay_offer before final answer, never quote price from search alone). This gives an agent unambiguous decision 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 already mark the tool as readOnly, idempotent, and non-destructive; the description adds substantial behavioral detail: it reads the domain's .well-known/vacation-rental.json and JWKS, refuses IPs/ports/local/private hostnames, enforces canonical-domain identity (www vs apex), and explains that trust is tied to the exact domain passed. 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?

Core purpose and constraints are front-loaded, and every sentence carries substantive guidance. Minor redundancy: the mechanism of reading .well-known and JWKS is stated twice, once in the second sentence and again in the final sentence, which prevents a perfect conciseness score.

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 single-parameter tool with an output schema and safety annotations, the description covers purpose, input constraints, usage context, trust semantics, and the required follow-up call to get_verified_stay_offer. Nothing needed to invoke it 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?

The schema has 100% coverage for the single domain parameter, so the baseline is 3, but the description extends meaning considerably: bare hostname only, public domains only, IPs/ports/local private hostnames refused, and canonical domain exact-match semantics with www/apex distinction. This goes well beyond the schema pattern and 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 states a specific verb ('Verify') and a specific resource ('vacation-rental host domain is a valid VRP node'), and explicitly excludes availability, pricing, booking, and payment, distinguishing it from sibling booking/search tools. It also names the successor tool (get_verified_stay_offer), clarifying its niche.

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 when to use: 'Use when a host domain arrives from outside search (user-typed or third-party)', and gives the alternative: domains from hemmabo_search_properties can go straight to get_verified_stay_offer. It also provides a clear negative directive: 'do NOT use it to answer those questions'.

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