HemmaBo Host Booking Engine

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds critical behavioral boundaries: 'must not lock a quote, create a booking, collect guest details, or start checkout.' It also reveals verification internals (Ed25519 JWS, JWKS) and the non-obvious fact that night count drives pricing rather than actual dates. 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 long but every sentence earns its place. It is front-loaded with purpose, then usage order, then behavioral rules, then parameter semantics. The language parameter explanation is verbose, but it prevents a subtle and costly misuse (rendering locale mismatch), so it 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?

For a tool with 5 parameters, an output schema, and complex preconditions, the description covers all necessary context: prerequisites (search or verification), postconditions (signed offer), side-effect boundaries, fallback paths, and parameter interactions. The output schema exists, so return-value documentation is not needed, but the description does not neglect it.

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, but the description adds substantial meaning: parameters 'work as a set,' checkIn/checkOut must be strictly ordered, the night count (not the raw dates) re-prices the offer, and language is purely a formatting concern that never affects price. These are cross-parameter semantics not present in the 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 opens with a specific verb+resource combination: 'Fetch, verify, and render a live host-domain signed VRP stay offer.' This clearly distinguishes it from sibling tools like hemmabo_booking_create or hemmabo_search_properties, and the explicit mention of 'live host-domain signed' adds unique 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 explicit temporal guidance: call after hemmabo_search_properties or verify_vacation_rental_node, and before quoting/booking. It also names alternatives (hemmabo_booking_negotiate/hemmabo_booking_checkout) and specifies exactly when to fall back (only when no signed offer, after explicit user confirmation). This is exemplary when-to-use vs. 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?

Annotations already declare `destructiveHint` and `idempotentHint`. The description adds important context: it processes a Stripe refund, requires a guest token (Bearer alone is insufficient), elaborates on idempotency (cancelling already-cancelled booking returns same status), and mentions rate limiting. Minor gap: doesn't describe what the response looks like, but output schema 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?

Every sentence adds unique value—purpose, usage rules, behavioral notes, parameter clarifications—without redundancy. Front-loaded with the core action, then provides guidance and constraints efficiently. No filler.

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 tool with 3 params, output schema present, and informative annotations, the description covers all critical aspects: purpose, prerequisites (guestToken), caveats (pending bookings expire automatically, idempotency), auth requirements, and cross-references to related tools. Leaves no ambiguity.

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%. The description goes beyond the schema by clarifying the relationship between `guestToken` and `Bearer token` (guestToken is mandatory and distinct), and explains that `reservationId` must be the booking UUID from specific sources (not a propertyId). Also adds guidance for `reason` (optional free text for 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 clearly specifies the verb 'Cancel', the resource 'confirmed booking', and the key action 'process the Stripe refund', fully differentiating this tool from its sibling `hemmabo_booking_reschedule`.

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 when to use this tool ('when the guest requests cancellation'), what not to do ('do not use for pending/unpaid bookings'), and explicitly names the alternative (`hemmabo_booking_reschedule`) for changing dates.

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 adds substantial behavioral context beyond annotations: it creates a pending booking and Stripe session server-side, is not idempotent (recommending checking hemmabo_booking_status before retrying), is rate-limited per token, and requires Authorization. These disclosures align with the annotations (idempotentHint=false, readOnlyHint=false) and provide actionable safety guidance.

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 carries information: purpose, use conditions, alternatives, auth, idempotency, rate limiting, and parameter semantics. It is front-loaded with the core action and is appropriately sized for a tool with 10 parameters, though it is slightly long and could benefit from structural breaks.

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's complexity (10 parameters, 6 required), the description covers purpose, usage boundaries, authentication, side effects, rate limits, and key parameter relationships. An output schema exists, so return values do not need explanation. The description is complete enough for an agent to decide when and how to invoke it safely.

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 meaningful cross-parameter semantics for quoteId (honor locked price vs fresh pricing), paymentMode, channel, and guest identity, going beyond the schema's individual descriptions. However, many parameters (propertyId, checkIn/out, guests) already have rich schema descriptions and gain little from the description.

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 clearly distinguishes this from siblings by positioning it as the fallback when no signed VRP direct_booking_url exists, and it names hemmabo_booking_create and get_verified_stay_offer as alternatives.

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?

Explicit guidance is provided: use only after explicit user confirmation when no signed direct_booking_url is available, route to get_verified_stay_offer when a signed URL exists, and use hemmabo_booking_create for pending bookings without payment. This gives clear when-to-use and when-not-to-use conditions with named alternative 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 description goes well beyond annotations by stating it is not idempotent, warns about rate limiting, mentions cancellation semantics ('check hemmabo_booking_status before retrying on timeout'), and details side effects ('Writes a pending booking server-side'). The annotations are consistent with these behaviors.

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 paragraph with no wasted sentences, front-loaded with the core action and conditions. Every sentence adds unique value, covering usage, prerequisites, safety, and parameter roles efficiently.

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's complexity (7 parameters, output schema present), the description completely covers when to use, how to prepare, behavioral traits, and warnings about non-idempotency and rate limits. The presence of output schema means return values need not be documented, and the description handles all other aspects.

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 schema already documents all parameters thoroughly. The description adds high-level context like 'guestName and guestEmail are required for host confirmation' and clarifies the role of 'propertyId' as coming from search, which is not 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 verb 'Create' and the resource 'pending direct booking', specifying it is 'without online payment for configured non-VRP fallback deployments'. This distinctively separates it from sibling tools like 'get_verified_stay_offer' or 'hemmabo_booking_negotiate'.

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 when to use this tool ('after explicit user confirmation, with a propertyId from search, and only when no signed VRP direct_booking_url is available'), when not to use it ('For signed VRP offers, route to the signed host-domain URL instead'), and provides clear context for decision-making.

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?

Beyond annotations (readOnlyHint=false, etc.), the description reveals important behaviors: it writes a server-side snapshot, is rate-limited per token, refuses impossible dates and returns alternates, and enforces that the quoteId is only valid for an identical parameter combination and until validUntil. These are critical for safe invocation.

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. The most vital clarification ('PRICE LOCK, not negotiation') is front-loaded, followed by usage, exclusions, and behavioral constraints. Structure is logical and prevents misinterpretation of the tool's name.

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's complexity and the presence of an output schema, the description fully covers purpose, conditions, behavior, auth, rate limits, parameter constraints, and the relation to checkout. Nothing important 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 covers all 4 parameters (100%), so baseline is 3. The description adds a critical interaction constraint: 'The parameters form one locked combination' and clarifies that night count and guest count together select the price tier, which adds value beyond individual parameter 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 explicitly states the tool's core function — it locks (freezes) the host's price for 15 minutes, not negotiates. It distinguishes from siblings by naming get_verified_stay_offer as the alternative for verified offers and explicitly listing prohibited use cases (search, availability, VRP offers, etc.).

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 conditions for use: 'only when no signed direct_booking_url is available and the user explicitly asks to lock a price.' Also gives explicit exclusions: 'Never use this for search, availability, VRP offers...' and points to the correct alternative tool (get_verified_stay_offer).

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=true and idempotentHint=true, but the description adds substantial behavioral detail beyond that: return contents (final total, per-night breakdown, package pricing), currency format (integers in local currency), and the sensitivity of pricing to date/guest changes ('changing any of them re-quotes'). It also flags the invalidity caveat when dates are unavailable, which is critical for correct invocation.

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 four sentences, each carrying relevant information: purpose, usage placement, return details, and pricing behavior. It is not overly terse, but every sentence earns its place with no filler or repetition of what annotations already state.

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 (read-only, idempotent) and full schema coverage for all 4 required parameters, the description appropriately covers the key aspects: what the quote returns, how to order it relative to availability checks, and a caveat about invalid quotes. It could ideally mention explicit error conditions, but the output schema and annotations fill most remaining 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% so the baseline is 3. The description adds meaningful parameter interplay by explaining that 'night count and party size together select the price tier' and that the quote is 'for the exact checkIn/checkOut range and guests.' This goes beyond individual parameter descriptions to clarify how the inputs jointly determine pricing.

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: 'Get a detailed pricing quote for a specific property, dates, and guest count.' This clearly distinguishes it from sibling tools like search, booking creation, and cancellation by focusing on the pre-booking pricing query step.

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 ('after confirming availability', 'before booking') and when-not-to-use ('Do NOT use before checking availability') guidance. However, it does not name an alternative tool to use instead, leaving the agent to infer from sibling names (e.g., hemmabo_search_availability).

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?

Beyond the annotations (destructiveHint: true), the description elaborates on the destructive nature: 'the original dates are released back to the host calendar and the original price no longer applies — the booking keeps the same reservationId (updated in place, never recreated), and the price difference is charged or refunded via Stripe.' It also mentions rate-limiting and authorization requirements, adding value beyond the structured fields.

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 well-structured and front-loaded with the main action, then usage guidance, then behavioral details. Each sentence earns its place, but it is slightly longer than strictly necessary; it could be tightened. Overall efficient and clear.

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's destructive write nature and the existence of an output schema, the description covers all critical aspects: behavior on execution, prerequisite checks, authorization model, parameter relationships, and side effects. It leaves no obvious gaps for an agent to misuse the tool.

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?

All 5 parameters have 100% schema description coverage, so baseline is 3. The description adds extra context by explaining how to use parameters together ('Identify the existing booking by reservationId, then give the new stay as newCheckIn/newCheckOut...'), reinforcing the relationship between parameters. While helpful, it does not add entirely new parameter details beyond schema, hence a 4.

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's purpose: 'Reschedule a confirmed or pending booking to new dates with automatic repricing and Stripe charge/refund.' It uses a specific verb and resource, and explicitly distinguishes itself from the sibling tool hemmabo_booking_cancel by contrasting changing dates versus ending the stay.

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 provides explicit when-to-use guidance ('Use when the guest wants to change dates on an existing booking'), when-not-to-use conditions ('Do not use if cancelled or if a protocol compatibility client reports completed'), and a prerequisite action ('check hemmabo_booking_status first'). It also names the alternative tool (hemmabo_booking_cancel) and explains the booking status check.

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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: 'Read-only against the database — never writes, so it is safe to poll after a checkout timeout', plus mentions PII in response and rate limits. 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 front-loaded with purpose, then provides usage guidance, behavioral traits, and parameter context in a logical flow. Every sentence adds unique value without redundancy.

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?

An output schema exists, so return values need not be detailed. The description covers all essential aspects: purpose, when to use, behavioral guarantees (read-only, polling safety, PII, rate limits), and parameter semantics. No gaps for a status retrieval tool.

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%, but the description still adds meaningful context: clarifies that reservationId must come from checkout/create (not propertyId), and explains the guestToken's unique role versus the Bearer token. This goes well beyond the schema's field 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 starts with a clear verb+resource combination: 'Retrieve current status and full details of an existing booking by reservationId.' It explicitly distinguishes this retrieval tool from siblings like hemmabo_search_properties and hemmabo_booking_quote, which serve different purposes.

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?

Explicit guidance is given: 'Use to confirm checkout/create succeeded or before cancel/reschedule.' It also states what not to use it for and lists four alternative tools by name. This fully satisfies the when/when-not 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 declare readOnlyHint=true and idempotentHint=true, and the description reinforces this with concrete non-actions: 'does not create a HemmaBo account, buy a domain, configure Stripe, write to Supabase, or provision a booking site.' It also discloses what the tool returns and that parameters are not stored server-side, adding valuable context beyond annotations. No contradiction.

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 front-loads purpose and guest exclusion. Every sentence adds distinct value (usage, non-actions, return contents, parameter behavior). Slightly more verbose than the TDQS 4.3 example, but still well-structured and free of 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 6 optional params, rich annotations, and an output schema, the description covers purpose, target user, usage timing, alternative tools, exclusions, return contents, parameter behavior, and storage semantics. Nothing important is left unaddressed; it is complete for effective agent selection and invocation.

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 each parameter already described. The description adds cross-cutting semantics: 'All parameters are optional and only enrich the returned onboarding URL' and 'nothing is stored server-side.' This exceeds the baseline for high schema coverage, though individual parameter details remain schema-driven.

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: 'Return a safe HemmaBo onboarding handoff URL' for a host wanting their own booking website/engine. It also clearly distinguishes from siblings by stating 'Not for guests — a guest looking for a place to stay should use hemmabo_search_properties instead.' This is a textbook clear purpose with sibling differentiation.

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?

Explicit when-to-use: 'Use after explaining the fit or when the host asks to start.' It also gives an alternative for a different phase: 'if the host is still evaluating whether HemmaBo fits, run hemmabo_host_readiness_check first.' The guest exclusion and explicit alternative make usage guidance exceptionally clear.

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?

Explicitly says 'Does not create an account, buy a domain, configure Stripe, store host data, or provision a website' which complements readOnlyHint/idempotentHint/destructiveHint annotations. Also discloses return content (fit verdict, what host gets, setup inputs, safe next step).

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?

Single paragraph, front-loaded with purpose and audience, each sentence adds information about usage, non-actions, parameter behavior; no fluff or redundancy.

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 11 optional params and an output schema, the description summarizes return values, explains parameter interplay, and provides tool alternatives. It covers all essential context for an agent to invoke 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 covers all 11 params (100%). Description adds that 'Every parameter is optional and additive' and explains that more parameters (propertyType, country/region/city, domain, currentChannels, wants* booleans) yield sharper verdict, with none returning generic summary – this goes beyond 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?

Description states 'Read-only fit check for a vacation-rental host evaluating HemmaBo for their own booking website or booking engine' – specific verb, resource, and audience. It explicitly contrasts with sibling hemmabo_search_properties for guests, distinguishing the two.

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?

States 'Use when the user is a host or property owner, not a guest booking a stay' and names hemmabo_search_properties as alternative for guests. Also directs follow-up to hemmabo_host_onboarding_link when host is ready.

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 critical behavioral details beyond annotations: 'Read-only: checking availability never places a hold or reserves dates.' It also describes the return behavior ('Returns available=true/false with conflict details and same-month alternative date windows when unavailable'), which complements the readOnlyHint and idempotentHint annotations without contradiction.

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 purpose and covers all necessary aspects without extraneous text. It is a bit longer than minimal but every sentence contributes useful guidance, making it well-structured and efficient.

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?

With an output schema present, the description need not explain return fields. It covers usage timing, exclusions, safety, and parameter nuances, making it complete for an AI agent to select and invoke 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?

The schema already provides 100% coverage with detailed parameter descriptions, so baseline is 3. The description adds meaningful semantics by explaining how to use 'guests' ('omit guests to check dates only, or pass it to get host-source totals') and linking 'propertyId' to its source ('from search'), elevating the score above 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 clearly states the tool's function: 'Check whether a specific property is available for the requested dates.' It distinguishes from sibling tools by explicitly directing general browsing to hemmabo_search_properties, making its scope unique and unambiguous.

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 usage context: 'Use this tool after the user has selected a property from hemmabo_search_properties and wants to confirm availability before getting a quote.' It also gives a direct exclusion: 'Do NOT use for general browsing — use hemmabo_search_properties instead.' Additionally, it specifies parameter usage ('Use the propertyId from search with the exact checkIn/checkOut range; omit guests...').

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?

Beyond annotations, description discloses that results drop properties below guest capacity or unavailable for exact range, and warns never to quote final price from search alone. It also specifies return fields and the 'combine as one filter' behavior.

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?

Four dense sentences, front-loaded with purpose, then usage, exclusions, return info, and filter behavior. No filler.

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?

With output schema present, description covers discovery workflow, exclusions, parameter combination, and result filtering. It provides necessary context for safe invocation.

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 covers 100% of parameters with descriptions. Description adds the 'combine as one filter' semantics and reiterates the checkIn/checkOut ordering, complementing schema without redundancy.

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 'Search available vacation rental properties by location and travel dates' with a specific verb and resource. It distinguishes from sibling get_verified_stay_offer by labeling itself 'Discovery only' and noting not to use when propertyId/host domain is known.

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 'Use when the user wants to find or browse places to stay' and 'Do NOT use when the user already has a propertyId or host domain.' Also directs to call get_verified_stay_offer after search, providing clear 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral specifics: it 'Reads the domain's .well-known/vacation-rental.json and JWKS,' explicitly states 'Read-only trust check: no availability, pricing, booking, or payment,' and notes the trust caveat 'the result is only as trustworthy as the exact domain you pass.' This goes beyond the 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?

Six sentences, each contributing unique information: purpose, mechanism, exclusions, usage timing, follow-up, and input caveat. No filler or repetition; appropriately dense for a trust-verification tool. A perfect score would require even tighter structure, but this is already quite efficient.

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?

With a full output schema and strong annotations, the description needn't explain return values. It covers purpose, input semantics, behavioral boundaries, alternatives, and success follow-up—sufficient for an agent to select and invoke correctly. Minor omission: failure behavior, but output schema likely covers that.

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% for the single domain parameter. The description reinforces the bare-hostname requirement ('no scheme or path') and ties the result's trustworthiness to the exact domain passed, adding semantic nuance beyond the schema's pattern and description. It does not introduce new parameter-level facts, so a 4 is appropriate.

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 ('Verify') and resource ('vacation-rental host domain') and clearly defines the outcome ('is a valid VRP node before trusting it'). It also distinguishes from siblings by stating it's a trust check, not for availability/pricing/booking/payment, and contrasts with get_verified_stay_offer.

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 when not to: 'domains returned by hemmabo_search_properties can go straight to get_verified_stay_offer.' It also provides follow-up guidance: 'On success, call get_verified_stay_offer...' and warns '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.