HemmaBo Host Booking Engine

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

Annotations already cover read-only/non-destructive, but the description adds substantial context beyond them: anonymous access with no Bearer token, rate limiting, no hold or reservation ever placed, fail-closed behavior on stale inbound calendar sync (calendar_freshness), and the exact failure reasonCodes (guests_exceed_max, min_nights_violation). It also clarifies that booking and payment happen only on the host domain, giving the agent a complete behavioral picture.

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 routing and never-present-as-price warnings are front-loaded, and most sentences carry unique constraints. There is mild redundancy between 'the same window the node's /api/availability reports' and the later 'verdict always matches the host node's own availability API,' and the block is long, but it is dense with non-repeating rules rather than 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?

An output schema exists so return values need not be spelled out, yet the description still summarizes the key response semantics (available=true/false with conflict details, at most one alternativeDates window). Combined with the auth, rate-limit, capacity, and min-nights rules, an agent has everything required to invoke it correctly and interpret the result.

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 real meaning beyond it: omitting guests checks dates only, and passing it both prices alternative windows and gates capacity, with counts above the property maximum returning available=false. It also ties checkIn/checkOut to stay length and the min-nights rule, though it does not add format detail to propertyId beyond 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?

States a specific verb and resource ('Check whether a specific property is available for the requested dates') and frames it as the yes/no availability question for one known propertyId. It distinguishes itself from hemmabo_search_properties (browsing) and vrp_get_verified_stay_offer (signed price/booking link) without the agent needing to open either schema.

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 names when to use it (after the user selects a property and wants to confirm availability before a quote) and when not to (general browsing -> hemmabo_search_properties; final price -> vrp_get_verified_stay_offer). It also instructs the agent to never present this tool's numbers as the final price, which is a concrete routing constraint.

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 confirm read-only safety, and the description adds substantial non-obvious behavior: it does not create accounts, buy domains, configure Stripe, store host data, or provision websites; booking and payment occur only on the host's own signed direct_booking_url; and the agent never books, pays, cancels, or changes bookings. It also discloses that this tool's next_step already includes the onboarding URL, preventing a duplicate tool call.

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?

Front-loads the triggering condition and the sibling routing rule, then layers scope, exclusions, and parameter weighting. Although long, every sentence carries routing, behavioral, or parameter semantics, and there is no filler or restatement of the structured schema.

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 an 11-parameter tool with an output schema, rich annotations, and five sibling tools, the description covers selection, exclusion, behavioral boundaries, parameter effects, and next-step coordination. Nothing an agent needs in order to call it correctly or avoid a duplicate call 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?

Though the schema already documents every parameter, the description adds semantic grouping and omission behavior the schema does not: only domain/hasOwnDomain, currentChannels, one location signal, and wants* booleans sharpen the verdict; wants* count unless explicitly false; omissions never lower the verdict; propertyName and preferredLanguage only prefill the onboarding URL; and no inputs produce a generic summary.

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 ('read-only fit check for a vacation-rental host evaluating HemmaBo') and distinguishes itself from siblings by naming hemmabo_get_host_onboarding_link and hemmabo_search_properties with the conditions that select each. An agent can route correctly without opening any schema.

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 when to use this tool ('when a host is still EVALUATING'), when not to use it ('only when the host has decided'), names the alternative for each case, and adds a hard coordination rule: never call both in the same turn. Also excludes guests by routing them to hemmabo_search_properties.

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 cover the read-only/non-destructive profile, but the description adds substantial context: it does not create an account, buy a domain, configure Stripe, write to Supabase, or provision a site; it lists what is returned (URL, category sentence, price atom, role, preparation items); nothing is stored server-side; and booking/payment only occur on the host's own domain. This is rich disclosure 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?

The content is valuable but the readiness alternative is stated twice in near-identical terms ('it returns the same onboarding URL in next_step' / 'it already returns the same prefilled URL in its next_step'), which is redundant. The purpose statement is also buried in the middle rather than front-loaded, so the definition reads longer than necessary.

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 annotations carrying the safety profile, a fully described 6-param schema, and an output schema, the description still covers prerequisites, exclusions, side-effect boundaries, and what the result contains. 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 collective semantics: all parameters are optional prefill, they never change where the host lands, blank values are simply omitted, and nothing is persisted. That clarifies the intent of the parameters beyond the per-field schema text.

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 states a specific verb and resource — it returns a HemmaBo onboarding handoff URL for a vacation-rental host — and explicitly carves out what it is not (not for guests) and which sibling it corresponds to. An agent can distinguish it from hemmabo_check_host_readiness and hemmabo_search_properties without opening any schema.

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 (host has already decided to start, or asks to start), when-not (host still evaluating), and the exact alternative (hemmabo_check_host_readiness), plus a hard constraint not to call both in the same turn. Routing is unambiguous.

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 destructiveHint=false, and the description adds substantial non-obvious behavior on top: results are price-free, prices and signed booking links come only from the offer tool, capacity misses are dropped while date misses surface in unavailableMatches with up to three alternates, and booking/payment happen only on the host's domain. It also explicitly bounds agent behavior ('never books, pays, cancels or changes a booking').

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?

Purpose and usage are front-loaded in the first two sentences, and nearly every later sentence carries operational payload (follow-up call, failure handling, booking domain). However, the single dense paragraph packs several independent concerns together and repeats the checkIn/checkOut constraint already in the schema, costing some readability.

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, yet the description still notes the key returned fields and, more importantly, covers the partial-failure path (unavailableMatches) and the mandatory offer-widget step the agent must complete. For a 5-parameter discovery tool with a downstream dependency, 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, but the description genuinely adds semantics the schema does not: parameters combine into a single filter, region performs a broad match across region/city/country while country matches only the country field, and omitting both widens the search to every published property. It also restates the checkIn-strictly-before-checkOut constraint, which is already covered 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?

Opens with a specific verb+resource+scope: 'Search available vacation rental properties by location and travel dates.' It also distinguishes itself from siblings by naming vrp_get_verified_stay_offer and stating the condition that excludes this tool (user already has a propertyId or host domain).

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?

Gives when-to-use ('find or browse places to stay'), when-not ('Do NOT use when the user already has a propertyId or host domain'), and a mandatory next step ('call vrp_get_verified_stay_offer ... before the final answer'). The routing decision is fully specified without 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the verification mechanism (Ed25519 JWS against domain JWKS), hard behavioral constraints (must not lock a quote, create a booking or collect guest details), the routing rule (booking only to the signed direct_booking_url), and where booking/payment actually occur. This is substantial context the annotations alone do not convey.

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 critical constraints are front-loaded and each sentence carries instruction. It is somewhat long and repeats the booking-on-host-domain idea across two sentences, but no sentence is pure filler, so it stays efficient for a tool with this much behavior to convey.

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-value detail is unnecessary. Given the 5-parameter schema, an open-world read tool, and the multi-step workflow, the description covers prerequisites, parameter coupling, date validation, pricing behavior, and downstream booking routing — enough for correct 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%, so baseline is 3, but the description adds relational semantics beyond the schema: 'the parameters work as a set' with matching domain/dates/guests from search, and the key insight that night count — not the dates themselves — drives signed price and capacity checks, meaning changing either date re-prices. It also explains language's non-effect on price. This genuinely extends 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 states a specific verb and resource — fetch, verify and render a live host-domain signed VRP stay offer for exact dates and guest count — and explicitly contrasts itself with siblings ('For a bare availability yes/no on a propertyId, hemmabo_check_availability is lighter and sufficient'). An agent can tell it apart from hemmabo_search_properties and vrp_verify_node without opening any schema.

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 ordering conditions: call after hemmabo_search_properties returns a host domain, or after vrp_verify_node confirms a domain from outside search, and always before quoting final price or a booking link. It also names the lighter alternative for the availability case, so both when-to-use and when-not-to-use are covered.

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/destructive/openWorld, and the description adds real behavioral context beyond them: it discloses that it fetches .well-known/vacation-rental.json and JWKS, that trust is bounded by the exact domain passed, that IPs/ports/local hostnames are refused, and that booking/payment happen only on the host's own signed direct_booking_url.

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?

Front-loaded with the core purpose and read-only scope, then sequenced into constraints and next steps. It is on the long side and the closing two sentences about booking/payment and the agent never booking are somewhat redundant, but each sentence still carries operational value.

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-value explanation is unnecessary, and the description covers everything else an agent needs: preconditions, exact-input rules, refusal cases, and the downstream call. Complete for a single-parameter verification 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 coverage is 100% and the schema already gives the pattern and invalid examples, so baseline is 3. The description adds genuine meaning beyond it — bare hostname form, refusal of IPs/ports/private hostnames, and the critical www-vs-apex canonical-domain identity rule that causes verification to fail on mismatch.

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 (verify) and resource (VRP node / host domain) and explicitly scopes it as a trust check separate from availability, pricing, booking, or payment. It names the sibling tools it routes to and from, so an agent can distinguish it without opening any schema.

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?

Gives explicit when-to-use (host domain arriving from outside search, user-typed or third-party) and when-not-to-use (domains from hemmabo_search_properties should go straight to vrp_get_verified_stay_offer), plus the required follow-up call with the same domain and dates. Nothing is left to inference.

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