HemmaBo Host Booking Engine

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

Annotations already cover readOnly/idempotent/destructive, but the description goes further by disclosing the cryptographic verification (Ed25519 JWS against domain JWKS), the set-semantics of the parameters, the re-pricing behavior when either date changes, and an explicit prohibition on side effects. This is unusually rich behavioral context 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?

Front-loaded with the core action, then sequencing, constraints, and parameter semantics in roughly priority order. Information density is high and most sentences earn their place, though the paragraph runs long for a tool description and could be split for scannability.

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 5-param, cryptographically-verifying, open-world tool with an output schema already present, the description covers sequencing, prerequisites, side-effect constraints, set-semantics, and rendering caveats. Return values are correctly left to the output schema.

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 genuinely new semantics: the parameters must be passed as a set matching the original search, night count (not the dates) drives price and capacity, and language never affects price/availability. It stops short of explaining every parameter's error modes, hence 4 rather than 5.

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 compound verb+resource ('Fetch, verify, and render a live host-domain signed VRP stay offer') and names the exact inputs it operates on. It clearly distinguishes itself from hemmabo_search_properties and verify_vacation_rental_node by positioning itself as the downstream signing 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?

Explicitly states when to call it: after hemmabo_search_properties returns a host domain, or after verify_vacation_rental_node confirms one from outside search, and 'always before quoting final price or a booking link'. It also gives a hard exclusion (must not lock a quote, create a booking, collect guest details, or start checkout) and routes booking to the signed direct_booking_url.

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, destructiveHint=false, so safety is covered. The description adds substantial beyond-annotation context: it enumerates side effects that do NOT occur (no account creation, no domain purchase, no Stripe config, no Supabase writes, no site provisioning), states nothing is stored server-side, notes params never change the landing page, and describes what the tool returns (URL, what the host gets, 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?

Front-loaded with the purpose and audience, then exclusions, then behavior. Every clause carries information, but the description is long and the negative-enumeration sentence ('does not create... buy... configure... write... or provision') is somewhat list-heavy. Still, no filler sentences.

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?

Output schema exists, so return-value explanation isn't required in prose; the description instead covers the key non-obvious facts (side-effect-free, prefill-only params, sibling handoff logic). With annotations and a full schema present, an agent has everything needed to select and call 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% and each param already documents purpose and examples, so baseline is 3. The description adds a genuinely useful meta-semantic not in the schema: all params are optional prefill that never change the destination, blanks are omitted, and nothing is persisted server-side. It does not add per-field semantics beyond what the schema gives, so capped at 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?

States a specific verb (return) and resource (safe onboarding handoff URL) for a specific audience (vacation-rental host), and explicitly distinguishes from siblings by naming hemmabo_search_properties as the guest-facing alternative. An agent can tell this apart from the search tools without opening schemas.

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 triggers ('after explaining the fit or when the host asks to start') and an explicit exclusion/alternative ('if the host is still evaluating... run hemmabo_host_readiness_check first'). Names both the when-to-use and when-to-use-something-else, with the reason (readiness_check already returns the same URL).

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 already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral context. It states what the tool does not do: create an account, buy a domain, configure Stripe, store host data, or provision a website, and it describes the returned fit verdict, setup inputs, and safe onboarding 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?

The description is front-loaded with the core purpose and routing guidance, and most sentences carry useful operational detail. It is dense and the long final sentence could be structured more clearly, but it is not padded with 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?

Given the tool's complexity, the rich annotations, the fully described 11-parameter schema, and the presence of an output schema, the description is complete enough to call it correctly. It covers scope, exclusions, input effects, return behavior, and the follow-up 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%, so the baseline is 3, but the description adds real semantic weighting by identifying which inputs sharpen the fit verdict and clarifying that omitting the wants* booleans never lowers it. It also explains that propertyName and preferredLanguage only prefill the onboarding URL. However, it says only five inputs sharpen the verdict while propertyType in the schema is described as affecting fit, creating a minor ambiguity.

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: a read-only fit check for vacation-rental hosts evaluating HemmaBo for their own booking website or booking engine. It explicitly separates hosts from guests and names the guest-oriented sibling tool, so an agent can distinguish it without opening the 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 guidance: use when the user is a host or property owner, not a guest booking a stay. It also names alternatives for both the guest path (hemmabo_search_properties) and the next host step (hemmabo_host_onboarding_link).

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 establish read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: anonymous access, rate limiting, no hold or reservation side effects, fail-closed behavior on stale calendar sync, and exact false-return conditions such as guests_exceed_max and min_nights_violation. This goes well beyond the structured 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 usage, then behavior, and most sentences carry necessary information. It is dense and somewhat long, with several packed clauses about edge cases, but little of it is redundant.

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, the rich input schema, and the presence of an output schema, the description is complete. It covers when to use it, when not to, access model, rate limits, side-effect safety, failure modes, and key result semantics without needing to explain the full return shape.

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 would be 3, but the description adds meaningful behavioral semantics for guests: omitting it checks dates only, providing it prices alternatives and gates capacity, and counts above the property maximum return available=false. It also clarifies the relationship between checkIn/checkOut and stay length and minimum-night violations.

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: checking whether a property is available for requested dates. It also explicitly distinguishes itself from the sibling hemmabo_search_properties by warning not to use it for general browsing. An agent can identify the exact operation without opening the 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 sequencing: use after the user has selected a property from hemmabo_search_properties and wants to confirm availability before getting a quote. It also states when not to use it and names the correct alternative for browsing. Additional guidance covers omitting guests, pricing alternatives, and capacity gating.

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?

Adds rich context beyond annotations: read-only is covered by annotations, but the description adds that search alone must never quote a final price or booking link, that date-unavailable matches return separately in unavailableMatches with up to three alternative windows, and that capacity misses are excluded. This is exactly the behavioral detail annotations do not cover.

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?

Well front-loaded: purpose first, then usage, then behavioral warnings, then parameter mechanics. Dense but every clause carries information. Slightly long but justified by the multi-part semantics.

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, routing to sibling, return fields (propertyId, host domain, availability, pricing, capacity), edge cases (capacity misses excluded, date-unavailable matches in unavailableMatches), and parameter interaction. An output schema exists but the description still appropriately summarizes returns. Nothing an agent needs to call this 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 baseline is 3. The description still adds value by specifying how region and country combine (region matches broadly against region/city/country; country matches country alone; omitting both spans all properties), and that checkIn is strictly before checkOut. This is useful cross-parameter logic not fully captured 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?

States a specific verb (search) and resource (vacation rental properties) with scope (by location and travel dates). Explicitly distinguishes from siblings by naming get_verified_stay_offer as the required follow-up and stating this is discovery only.

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?

Front-loads when to use ('find or browse places to stay') and when not ('already has a propertyId or host domain'). Also names the mandatory alternative workflow (call get_verified_stay_offer before final answer), leaving nothing ambiguous.

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, but the description adds substantial context beyond them: it reads the domain's own .well-known and JWKS, refuses IPs/ports/local/private hostnames, and explains the canonical-domain identity rule (www vs apex, declared canonical_domain mismatch causes failure). These are exactly the behavioral traits an agent needs and cannot get from 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?

Front-loaded with purpose and scope before the usage rules, and nearly every sentence carries an operational constraint. The closing sentence restates the canonical-domain trust caveat already made earlier, which is mild redundancy 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?

For a one-parameter read-only verification tool with an output schema, everything an agent needs is present: what it reads, the failure conditions (private hosts, canonical mismatch), and the exact next call. Return values are covered by the output schema, so no gap remains.

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 the single 'domain' parameter and its pattern. The description adds genuine meaning beyond the schema: bare hostname only, public domains only, and the subtle canonical-identity semantics (www and apex are distinct, pass the canonical domain exactly). It stops short of 5 because the schema pattern already constrains the format.

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 ('Verify that a vacation-rental host domain is a valid VRP node') and immediately scopes what it reads (.well-known/vacation-rental.json and JWKS). It clearly distinguishes itself from get_verified_stay_offer and hemmabo_search_properties, so an agent can route between them without opening schemas.

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 ('when a host domain arrives from outside search — user-typed or third-party'), an explicit alternative for the other case (domains from hemmabo_search_properties go straight to get_verified_stay_offer), and negative guidance (do NOT use to answer availability/pricing/booking/payment). It also names the follow-up call on success.

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