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

Adds significant detail beyond readOnlyHint: verifies Ed25519 JWS against domain JWKS, must not lock quote/create booking/collect guest details, and that night count (not dates) drives price so date changes re-price. Also clarifies language only affects formatting. 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?

While dense, every sentence provides operational guidance—purpose, verification, when-to-call, side-effect restrictions, fallback, parameter semantics, and language formatting. Front-loaded with the core purpose and follows a 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?

The description covers when, why, and how to use the tool, its side effects, fallback behavior, and parameter interdependencies. With an output schema present, return values are documented elsewhere; the description sufficiently completes the context.

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?

Description explains the parameters as a set requiring consistency with search values, imposes checkIn before checkOut, clarifies that night count drives pricing, and instructs to always pass language despite not being listed as required in the schema. This is meaningful guidance beyond the schema's per-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 first sentence clearly defines the tool's function: fetch, verify, and render a live host-domain signed VRP stay offer. It distinguishes from search tools by noting it requires a host domain from search results and from booking tools by stating it must be called before quoting.

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: after hemmabo_search_properties returns a host domain or verify_vacation_rental_node confirms a domain, and before quoting final price. Naming hemmabo_booking_negotiate and hemmabo_booking_checkout as fallbacks only when no signed offer is returned provides clear alternative 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 mark the tool as destructive and idempotent, but the description adds critical specifics: 'a repeat cancel is refused as already cancelled and never triggers a second refund,' 'Rate-limited per token,' and the distinction that a Bearer token alone is insufficient without a matching guestToken. It also clarifies that it only applies to confirmed bookings and that the reason is shown to the host, with a default message. This goes well beyond the annotation hints and gives the agent a clear behavioral model.

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. It is front-loaded with the core purpose, then moves to usage boundaries, then behavioral cautions, then parameter-specific clarifications. There is no repetition or filler. The length is proportionate to the tool's complexity (three parameters, destructive effect, auth nuances). Structurally clear 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?

For a destructive, idempotent tool with an output schema (which covers return values), the description covers all necessary operational context: when to use, when not to use, alternatives, security requirements, parameter constraints, and side effects. The presence of an output schema means the description need not describe the return payload, so no essential information is missing. An agent can confidently call this tool correctly based on the description alone.

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 the schema covers 100% of parameters, the description significantly enriches understanding. It explains that guestToken is a per-booking secret returned at creation/checkout, that it grants no authority over other bookings, and that a valid Bearer token is not sufficient. It clarifies reservationId must be a booking UUID, never a propertyId, and must be paired with the matching guestToken. The reason parameter's optionality and default text are also described. These details are essential for correct invocation and go far 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 opens with a specific verb and resource: 'Cancel a confirmed booking and process the Stripe refund per host cancellation policy.' It clearly states what action is performed and on what object, and distinguishes it from the reschedule sibling by naming the alternative explicitly. The purpose is unambiguous and cannot be confused with any of the other 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?

The description provides explicit when-to-use and when-not-to-use guidance: 'Use when the guest explicitly requests cancellation — if the guest wants new dates instead of ending the stay, use hemmabo_booking_reschedule instead. Do not use for pending/unpaid bookings — those expire automatically.' It also directs the caller to preview the policy via hemmabo_booking_status. This is textbook usage guidance with named alternatives and excluded scenarios.

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, setting the baseline at 5, and the description further enriches semantics: 'channel selects which locked total is used; paymentMode changes only the handoff form, never the price' adds business logic. It also mentions 'Returns a one-time guestToken' (output) which complements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line 'Create a fallback non-VRP booking and return a host-configured checkout URL' is somewhat convoluted and grammatically tortured, but the second sentence clarifies that this is the fallback when the primary VRP flow is unavailable. The reference to get_verified_stay_offer helps disambiguate it from siblings, though the exact overloading of 'non-VRP' requires parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

With annotations present (readOnlyHint=false, idempotentHint=false), the description adds meaningful context: 'Writes exactly one pending booking awaiting the host's decision', 'conflicts or a stale calendar fail the call before anything is written', 'Not idempotent', plus auth requirements and per-token rate limiting. These go well beyond the structured annotations and match them with 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 long (about 200 words), but every sentence carries substantive operational or routing information for a complex 7-parameter mutation. It is front-loaded with the core purpose and then flows from usage constraints to behavior to parameter clarifications. Slightly dense, but justified by the complexity.

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 mutation complexity, an output schema already covers return values, and the description covers everything an agent needs: when to use vs alternatives, auth, rate limits, atomicity of failure, retry behavior, idempotency, pricing semantics, and required-field rationale. No meaningful 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 baseline is 3; the description adds value on top by explaining what is NOT a parameter ('There is no price or quoteId parameter — the node prices the stay itself'), how the booking is identified ('propertyId + the checkIn/checkOut range + guests'), and why guestName/guestEmail are required (host confirmation). This is genuine semantic enrichment 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?

The description states a specific action and resource ('Create a pending direct booking without online payment for configured non-VRP fallback deployments') plus boundary conditions. It differentiates cleanly from sibling booking tools like hemmabo_booking_checkout, hemmabo_booking_quote, and hemmabo_booking_negotiate by specifying the pending state and non-VRP fallback 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?

Explicitly conditions usage: 'Use only after explicit user confirmation, with a propertyId from search, and only when no signed VRP direct_booking_url is available.' It also names the alternative path ('route to the signed host-domain URL instead') and the retry precondition ('check hemmabo_booking_status before retrying on timeout'). 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.

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, and the description goes far beyond them: it thoroughly discloses non-idempotence (each call writes a new snapshot, re-locking returns a new quoteId), the fixed validUntil that never extends, the channel selection behavior in checkout, and the explicit rule that the quoteId is only redeemable for identical inputs. It also admits what the tool does NOT do (never bargains, discounts, or alters the price). This matches annotations and adds substantial behavioral context.

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 and front-loaded with the most critical fact (the tool is a lock, not a negotiation). Every sentence adds behavioral or routing value, with no fluff. However, it is quite long for a tool description and could be slightly trimmed without losing substance, so it's not a perfect 5. The length is justified by the complexity of the behavioral rules, so it earns a 4.

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 (non-idempotent, time-limited, channel-dependent) and the rich input/output schemas and annotations, the description is remarkably complete. It covers what the tool does, when to use it, what it refuses to do, the locking mechanics, the redemption constraints, and the exact conditions for reproducibility. The output schema exists, so return values are covered elsewhere, and nothing critical an agent needs to invoke it correctly is missing. The description fully compensates for the tool's complexity.

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 meaningful value on top: it explains that 'night count and guest count together select the locked price tier', clarifies that checkIn/checkOut define the stay length 'used for pricing and availability', and frames guests as tier-determining. It also reiterates the requirement to pass the exact property UUID. This goes beyond what the schema alone provides, though it doesn't add syntax details for each parameter. Given full schema coverage plus additional tier/price context, 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 is exceptionally explicit: it begins by reframing the tool's name ('PRICE LOCK, not negotiation'), names the exact verb (freezes a price for 15 minutes), the resource (current host-source price), and the scope (only in the non-VRP fallback checkout flow). It clearly distinguishes itself from get_verified_stay_offer and other siblings, and its title 'Lock Price Quote' is consistent, so there's no ambiguity about what action this tool performs.

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, precise usage instructions: use only in the non-VRP fallback checkout flow, only when no signed direct_booking_url is available, and only when the user explicitly requests to lock a price. It also names exclusions and the alternative tool (get_verified_stay_offer), and lists many contexts to avoid (search, availability, VRP offers, rendering a stay-offer widget). This is essentially a perfect usage-guide.

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?

Description adds behavioral context beyond annotations: prices are integers in local currency (SEK), the quote is specific to exact checkIn/checkOut and guests, and changing any parameter requires re-quoting. Annotations already indicate read-only, idempotent, non-destructive, which aligns.

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?

Description is concise (3 sentences), front-loaded with the core purpose, and each sentence adds crucial information 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?

Given the presence of an output schema for return values, the description fully covers usage order, parameter semantics, currency, and pricing logic. No gaps for this tool's complexity.

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 adds valuable semantic context, e.g., explaining that night count and party size together select the price tier, implying interdependency. This enhances understanding 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 clearly states the tool's purpose: getting a detailed pricing quote for a property, dates, and guest count. It distinguishes from siblings by specifying usage order (after availability check) and return details (final total, per-night breakdown).

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 instructs to use only after confirming availability and warns against using before, as the quote may be invalid. This provides clear when-to-use and 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?

Despite annotations already declaring destructiveHint=true and readOnlyHint=false, the description adds significant context: it warns that the original dates are released to the host calendar, the original price no longer applies, the booking is updated in place (never recreated), and that Stripe will charge/refund the difference. It also notes rate-limiting, auth requirements, and that the guestToken is required in addition to the bearer token—critical behavioral details 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 description is dense but every sentence adds value. It covers purpose, usage alternatives, exclusions, effects, auth requirements, and parameter specifics in a compact space. The structure flows naturally from what→when-not→behavior→parameters. There is zero filler 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 the complexity of this tool (destructive write, auth nuance, repricing, Stripe interaction), the description is remarkably complete. It covers auth (Bearer + guestToken), destructive effects (dates released, price changes), identity (same reservationId), parameter constraints (new dates ordering), and re-pricing behavior. The output schema likely covers return values, so no need to duplicate that. This is a model of completeness.

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 description adds substantial meaning beyond the schema. For guestToken, it explains why it's required even with a valid bearer token, that it's a per-booking secret, and that it must be the exact token from creation. For newCheckIn/newCheckOut it reiterates the ordering constraint and hints at repricing based on night count. For reservationId it explains it's updated in place. This far exceeds what the schema provides, compensating for the 100% schema coverage by adding valuable context.

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 purpose is exceptionally clear: 'Reschedule a confirmed or pending booking to new dates with automatic repricing and Stripe charge/refund.' It names the specific action (reschedule), the target (booking), the key behaviors (repricing, Stripe), and distinguishes from the sibling cancel tool. The verb+resource combination is precise 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?

The description provides explicit usage guidance: use when a guest wants to change dates, NOT when they want to end the stay entirely (use hemmabo_booking_cancel). It also warns against use if the booking is cancelled or completed, directing to check hemmabo_booking_status first. It clearly states when to use, when not to use, and names 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it returns guest PII, is safe to poll, requires a Bearer token, and explains the guestToken requirement in depth. This significantly exceeds annotation-only transparency.

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 packed with pertinent information, each sentence contributing unique value. It is front-loaded with the primary purpose and use cases, maintaining clarity 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?

The description provides complete context for invocation: when to use, safety, auth, parameter origins, and behavioral implications. Since an output schema exists, not explaining the return value 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?

Both parameters have detailed schema descriptions covering format, source, and necessity. The description adds further clarification that reservationId is never a propertyId and guestToken is a per-booking secret, enriching 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 retrieves current status and full details of an existing booking by reservationId, and explicitly distinguishes it from discovery, availability, and pricing tools. It names the specific sibling tools to avoid confusion.

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 (confirm checkout/create, before cancel/reschedule) and when-not-to-use guidance, pointing to alternative tools. It also notes the required authorization and rate limiting.

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 reinforces and extends this by explicitly listing what it does not do: no account creation, no domain purchase, no Stripe configuration, no Supabase writes, no booking-site provisioning. It also clarifies that parameters are only prefill and never affect the landing page, and nothing is stored server-side – valuable behavioral context 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 description is long but every section earns its place: primary purpose, explicit alternatives, read-only safety disclaimers, parameter prefill semantics, and return-value scope. It is front-loaded with the action and audience, then handles exclusions and behavioral guarantees without repetition.

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 moderate complexity, six optional parameters, rich annotations, and an output schema, the description covers everything an agent needs: when to call it, what it returns, what it does not do, how parameters behave, and how it relates to siblings. There are no meaningful gaps left for the agent to infer.

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 adds important cross-cutting parameter semantics: all parameters are optional prefill, they never change the destination URL, blank values are omitted, and nothing is stored server-side. This tells the agent the six parameters collectively behave as lightweight prefills rather than affecting routing or behavior, which the per-property schema descriptions do not convey.

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 the specific verb and resource: returning a safe HemmaBo onboarding handoff URL for vacation-rental hosts. It also explicitly contrasts it with hemmabo_search_properties and hemmabo_host_readiness_check, so the agent can distinguish it from the most similar siblings without inspecting their 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?

It states exactly when to use the tool ('after explaining the fit or when the host asks to start'), when not to use it ('Not for guests'), and which sibling to use instead for guests (hemmabo_search_properties). It also routes evaluative conversations to hemmabo_host_readiness_check, which already returns the same URL, giving explicit alternatives and conditions.

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, destructiveHint=false. The description reinforces these by stating it does not create accounts, buy domains, configure Stripe, or provision websites. It adds valuable context about input sensitivity (what counts toward the verdict and what only prefills the URL) and the no-input generic summary behavior. A 4 is appropriate because behavior is well-disclosed, though not everything is covered (e.g., exact verdict format), but the description exceeds the baseline given annotation coverage.

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 information-dense but quite long and runs on as a single paragraph. The most critical routing guidance (host vs guest) is front-loaded, but the deep parameter semantics are buried mid-paragraph and require careful reading. It earns its length given the 11 parameters and nuanced behavior, but could be better structured with separate sentences for clarity. It's not concise, but it is purposeful.

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 complexity (11 optional parameters, nuanced input semantics, output schema present), the description covers everything an agent needs: who should use it, what it returns (fit verdict, host benefits, setup inputs, next step), what it does not do, and how inputs affect the verdict. The existence of an output schema covers return value details. No critical operational detail is missing 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 description coverage is 100%, so the schema handles basic parameter meaning. The description adds significant semantic value beyond the schema: it distinguishes 'countable' inputs (domain, currentChannels, location, wants* booleans) from prefilling-only inputs (propertyName, preferredLanguage), explains that omitting wants* booleans never lowers the verdict, and states that no inputs yield a generic summary. This is meaningful guidance on how parameters affect the tool's output, well 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?

The description clearly states this is a read-only fit check for hosts evaluating HemmaBo, distinguishing it from guest-oriented tools. It specifies the resource (host readiness) and the context (own booking website/engine) with precise verb 'fit check produces verdict'. It explicitly names the sibling tool hemmabo_search_properties as the alternative for guests, making differentiation 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?

The description gives explicit usage criteria: use when user is a host, not a guest. It names the exact alternative (hemmabo_search_properties) and the follow-up action (hemmabo_host_onboarding_link). It also specifies what the tool does NOT do (create account, buy domain, configure Stripe, etc.), providing clear when-not 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 readOnly, idempotent, and non-destructive hints. The description goes well beyond: it discloses anonymous access (no Bearer token), rate limiting, that it never places holds or reserves dates, fails closed on stale calendar sync, returns conflict details and alternative windows, and explains exact outcomes for guests exceeding max and min-nights violations. This is rich behavioral context that annotations do not capture.

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, then behavioral details. No fluff or repetition. The complexity of the tool justifies the length, and the structure is logical and easy to scan.

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 four parameters and a rich set of edge cases, the description covers all essential aspects: when to use, what it returns (available flag, conflict details, alternatives, failure modes), how guests alter behavior, min-nights rule, anonymous access, rate limits, and the guarantee that the verdict matches the host API. Nothing an agent needs to 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%, but the description adds significant meaning beyond each parameter's schema definition. For guests, it explains the nuanced behavior of omitting versus passing a count, and how it affects alternative windows and capacity. For checkIn/checkOut, it clarifies that stay length is derived from their relation and that min-nights violations are handled via reasonCode. This substantially enriches parameter understanding.

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 first sentence states a specific verb ('Check'), resource ('a specific property'), and scope ('for the requested dates'). It clearly distinguishes from hemmabo_search_properties (search vs. availability) and hemmabo_booking_quote (availability before quote), making the tool's role unambiguous even without reading 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?

Explicit guidance is given: '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 states when NOT to use it ('Do NOT use for general browsing') and names the alternative (hemmabo_search_properties). Further usage nuances (omit guests for date-only check, pass guests to price alternatives) are provided.

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?

While the annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, the description adds substantial behavioral context: it states that the tool is discovery-only, that it returns live availability and host-source pricing (not final prices), and that capacity misses are excluded while date-unavailable matches are returned separately in unavailableMatches with up to three alternative windows. It also explains how region and country match semantics differ. This goes well beyond the annotations, providing an agent the full 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 description is dense and single-paragraph, but every sentence serves a purpose. It flows logically: purpose, when to use, follow-up requirement, exclusions, return details, and parameter behavior. While it could be split into bullet points for clarity, it is not verbose and information is front-loaded with the main purpose. The length is justified given the tool's complexity, so a 4 is appropriate.

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 search tool with 5 parameters, an output schema, and nuanced behavior (filtering, availability, alternative matches), the description is remarkably complete. It explains the return fields (propertyId, host domain, live availability, host-source pricing, capacity), the handling of capacity and date-unavailable properties, and the interaction between region and country. The existence of an output schema means return value details need not be repeated. Nothing an agent needs to invoke this tool 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 input schema already documents each parameter with descriptions (100% coverage), so the baseline is 3. The description adds extra value by explaining how parameters combine as one filter (guests with checkIn/checkOut range), that checkIn is strictly before checkOut, that region matches broadly against region/city/country while country matches only the country field, and that omitting both spans all properties. It also clarifies the role of guests in capacity and pricing tiers. This supplements the schema meaningfully, though not every parameter need is covered beyond what's 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 states the exact verb ('Search'), the resource ('available vacation rental properties'), and the criteria (location and travel dates). It also distinguishes from siblings by explicitly stating that it is discovery-only and should not be used when a propertyId or host domain already exists, and that get_verified_stay_offer is the follow-up. This unequivocally defines the tool's role relative to the other hemmabo 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?

The description gives explicit guidance on when to use the tool ('when the user wants to find or browse places to stay') and when NOT to use it (when the user already has a propertyId or host domain). It also requires a mandatory follow-up call to get_verified_stay_offer before the final answer, and warns against quoting prices or booking links from search alone. This is exemplary usage guidance with clear exclusions and 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only trust check' and 'no availability, pricing, booking, or payment.' It goes further by disclosing that it reads the domain's .well-known/vacation-rental.json and JWKS, that verification fails when the passed domain differs from the declared canonical_domain, that IPs/ports/local/private hostnames are refused, and that the result is only as trustworthy as the exact domain passed. This fully discloses behavior 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 description is dense but every sentence earns its place. It front-loads the core purpose, then alternates between usage rules, parameter constraints, and behavioral caveats. There is no redundant phrasing; each clause adds distinct, operationally relevant information. Despite its length, it is a model of purposeful prose.

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 (trust verification, canonical domain nuance, read-only contract, and follow-up action), the description covers all necessary context: when to apply, how to call, what to expect on success, and what failure conditions look like. The presence of an output schema further reduces the need to describe return values, and nothing an agent needs to call this tool 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?

Although the schema already describes the domain parameter with a pattern and example, the description adds crucial semantics: it must be a bare hostname (no scheme/path), public domains only, and the canonical domain must be passed exactly (www vs apex are distinct). It even warns about the failure condition for canonical domain mismatch, which is not in the schema. This materially improves agent correct invocation.

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 precise verb and object: 'Verify that a vacation-rental host domain is a valid Vacation Rental Protocol (VRP) node before trusting it.' It explicitly differentiates from siblings by stating that domains from hemmabo_search_properties do not need this verification and can go straight to get_verified_stay_offer, which clearly distinguishes its role.

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 and when-not-to-use guidance: use when a host domain arrives from outside search (user-typed or third-party), and do NOT use it for availability, pricing, booking, or payment. It also names the alternative (hemmabo_search_properties) and instructs the exact follow-up call (get_verified_stay_offer) on success, leaving no ambiguity about its place in the workflow.

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