Search and book verified independent vacation rentals directly from hosts, with no guest fees.
Scored across 10 tools
Most tools have clearly distinct purposes across the booking lifecycle (search, availability, quote, request, cancel, retrieve). The one fuzzy boundary is ask_host vs send_message, which are both host-communication tools and could be confused despite descriptions hinting at different backing endpoints. Otherwise selection is unambiguous.
All ten tools follow a strict verb_noun snake_case pattern (ask_host, cancel_booking, check_availability, get_booking, get_messages, get_property, get_quote, request_booking, search_stays, send_message). Verb choice is intuitive and predictable across the set.
Ten tools is well within the ideal 3-15 range and each maps to a distinct step in the guest booking flow. No redundant or filler tools appear.
The set covers a full guest-side lifecycle: search, property detail, availability, binding quote, booking request, cancel, retrieval, and messaging. Minor gaps exist (no way to list a guest's bookings or modify an existing booking), but agents can work around these via known booking IDs.
Send a question the property record and FAQ don't answer. The answer arrives later; tell the guest you'll follow up. Don't include the guest's contact details. Maps to POST /v1/properties/{id}/questions.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The guest's question, in plain words, up to 500 characters. The host's answer may be added to the listing's FAQ. | |
| property_id | Yes | The property the question is about. |
| Name | Required | Description |
|---|---|---|
| answer | No | |
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-destructive write with open-world effects, but the description adds the crucial asynchronous trait (the answer arrives later), the required guest-facing follow-up behavior, and a privacy constraint on the payload. That is meaningful disclosure beyond the annotations, though it does not cover failure modes or what the host sees.
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?
Three compact sentences, front-loaded with the use condition, then the async/follow-up behavior, then the privacy rule. Each sentence carries distinct, actionable information; even the endpoint mapping is a one-clause addition.
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 only two required parameters, an output schema present, and annotations covering the safety profile, the description supplies everything else the agent needs: why to choose this tool, that the result is deferred, and how to handle the guest in the interim.
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 both property_id and question are already documented, including the 500-character limit and the note that answers may be added to the FAQ. The description's only added parameter-level guidance is the 'no contact details' content rule, so the baseline 3 applies.
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 (send a question to the host) and immediately scopes it: questions the property record and FAQ do not cover. An agent can distinguish this from send_message and get_property 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 a clear triggering condition (only when the record and FAQ do not answer it) and two operational rules: tell the guest you will follow up, and exclude the guest's contact details. It stops short of explicitly naming the alternative routing (e.g., send_message for direct contact), so it is strong context rather than full when/when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Two-step. First call with confirm=false to see what the guest gets back if they cancel now (nothing changes). Tell the guest that refund and get their go-ahead, then call again with confirm=true and expected_refund_cents set to the refund amount from the first call. If the refund changed in between, the call fails with refund_changed instead of cancelling. Refunds go to the guest's card automatically. Pass guest_email (the email the booking was made with) unless you connect with an agent token.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | False to preview the refund without changing anything; true to cancel. | |
| booking_id | Yes | The booking or request to cancel. | |
| guest_email | No | The email the booking was made with. Needed unless you connect with an agent token. | |
| expected_refund_cents | No | Required when confirm is true: refund.amount from the confirm=false call. |
| Name | Required | Description |
|---|---|---|
| refund | No | An amount in cents with its currency. |
| booking | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, idempotent, openWorld), the description discloses the two-step safety pattern, that the preview is side-effect-free, that refunds go to the guest's card automatically, and a specific failure mode (refund_changed aborts the cancellation). It also covers the auth nuance around guest_email vs. agent token, which annotations 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?
Five tight sentences, front-loaded with 'Two-step.' Every sentence carries operational weight: the preview semantics, the required handoff to the guest, the confirmation call, the failure mode, and the auth exception. No filler or repetition of schema 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?
An output schema exists, so return values need no explanation, and the description covers the remaining burden for a destructive mutation: sequencing, side effects, failure behavior, and authentication. Nothing an agent needs to invoke this safely and correctly appears to be 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 real meaning: expected_refund_cents must be the refund.amount from the prior confirm=false call, and passing a stale value triggers refund_changed. It also clarifies guest_email is the email the booking was made with and is only skippable with an agent token.
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+resource (cancel a booking or request) and immediately frames it as a two-step preview-then-commit operation. It is unambiguous about what the tool does, though it never explicitly contrasts itself with siblings like get_booking or request_booking, leaving that differentiation to the reader.
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 clear procedural when-to-use guidance: call first with confirm=false to preview (nothing changes), get the guest's go-ahead, then call with confirm=true. It also states the guest_email requirement and the agent-token exception. What's missing is any explicit routing against alternative tools (e.g., when to read a booking instead of cancelling it).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Day-by-day availability and indicative nightly prices for up to 180 days. Cached; use get_quote to confirm. Useful when the guest's dates are flexible. Maps to GET /v1/properties/{id}/availability.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Exclusive | |
| from | Yes | First night to check, YYYY-MM-DD. | |
| property_id | Yes | The property's id, from search_stays. |
| Name | Required | Description |
|---|---|---|
| days | No | |
| timezone | No | |
| property_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: results are cached, prices are indicative rather than binding, and there is a 180-day ceiling. That cached/stale caveat is exactly the kind of operational detail annotations cannot express.
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?
Three short sentences, zero filler. Return content is front-loaded, followed by the usage trigger, the confirmation caveat, and the endpoint mapping last.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. Between the annotations, the 100%-covered schema, the caching/indicative-price caveat and the get_quote pointer, an agent has everything needed to call this correctly for a flexible-date search.
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 a real parameter constraint not present in the schema: the from/to window cannot exceed 180 days. The schemas own notes (from = first night, to = exclusive) remain the source of truth for semantics.
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 resource (day-by-day availability plus indicative nightly prices) and scopes it precisely to 180 days, so an agent knows exactly what comes back. It partially differentiates from siblings by pointing at get_quote, but does not clarify its relationship to get_property or search_stays, which also touch the same property entity.
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?
'Useful when the guest's dates are flexible' gives a clear positive trigger, and 'use get_quote to confirm' routes the agent to the alternative for firm pricing. It stops short of an explicit when-not (e.g. 'do not use this for a confirmed booking price'), so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status, amounts, refund schedule, guest ID verification link, and when arrival details will be sent. Maps to GET /v1/bookings/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | The booking's id, from request_booking (starts with bkg_). |
| Name | Required | Description |
|---|---|---|
| id | No | |
| total | No | An amount in cents with its currency. |
| status | No | e.g. awaiting_payment, pending_host_confirmation, confirmed, declined, cancelled. |
| check_in | No | |
| check_out | No | |
| property_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that responses include a guest ID verification link and the timing of arrival details—useful context—but these are return-value facts already carried by the existing output schema, so added value is limited.
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?
Two compact sentences/fragments with no filler, and the field list is front-loaded. It loses a point only because the leading fragment reads as a value list rather than an action, which forces the reader to reconstruct the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read with an output schema and read-only annotations, the description is adequate but thin. Because the output schema already documents the returned fields it enumerates, the description should instead have spent its words on when to use it, whether the data is live/cached, and what happens for unknown or cancelled booking IDs.
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?
Only one parameter, and the schema fully documents it (100% coverage) including the bkg_ prefix and its origin in request_booking. The description's endpoint mapping corroborates that booking_id is a path identifier but adds no new format or constraint detail.
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 never states a verb for the action; it is a list of returned fields plus the endpoint mapping GET /v1/bookings/{id}. That endpoint does imply retrieval of a single booking, but the agent must infer it, and there is no explicit differentiation from siblings like get_quote or check_availability beyond the endpoint path.
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?
There is no statement of when to call this versus alternatives such as get_quote, check_availability, or get_messages. The only implicit cue is the booking_id parameter description pointing back to request_booking, which suggests post-booking use but is not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The conversation between the guest and the host about a booking, oldest first (including the guest's note with the request and the host's note when accepting or declining). Use it to relay the host's replies. Pass guest_email (the email the booking was made with) unless you connect with an agent token.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | The booking's id, from request_booking (starts with bkg_). | |
| guest_email | No | The email the booking was made with. Needed unless you connect with an agent token. |
| Name | Required | Description |
|---|---|---|
| messages | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the chronological ordering, the inclusion of the guest's request note and the host's accept/decline note, and the auth shortcut for agent tokens.
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 resource and its ordering, then the intended use, then the parameter caveat. Three tight clauses with no padding, though the guest_email instruction duplicates the schema wording.
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-format detail is unnecessary. The description covers scope, ordering, and the auth requirement, which is enough to call the tool correctly; only an explicit pointer to the sibling write tool 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 description coverage is 100%, so both parameters are already documented with their formats and the bkg_ prefix. The description's note about guest_email largely restates the schema's 'Needed unless you connect with an agent token', adding no new syntax or format detail.
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 — reading the guest/host conversation about a booking — and even specifies ordering ('oldest first') and the included notes. An agent can tell this apart from send_message/ask_host (which write) and get_booking (which returns booking data, not the thread).
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?
'Use it to relay the host's replies' gives a clear context for invocation, and the guest_email/agent-token note signals the auth conditions. It stops short of explicitly naming send_message as the counterpart for replying, so it is context rather than full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full record for one property: beds by room, amenities with details, access and stairs, rules, host FAQ, policies, and verification status. The location is approximate on purpose: the exact address and the host's direct contact details are not in the record and are sent to the guest after a confirmed booking, so if asked, say that rather than that they are missing. Maps to GET /v1/properties/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| property_id | Yes | The property's id, from search_stays (starts with prop_). |
| Name | Required | Description |
|---|---|---|
| id | No | |
| faq | No | |
| rules | No | |
| listing | No | |
| capacity | No | |
| location | No | |
| policies | No | |
| amenities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/non-destructive annotations, it discloses a non-obvious data limitation — the location is deliberately approximate and the exact address plus host direct contact are withheld until a confirmed booking — and prescribes the correct phrasing so the agent does not report them as missing. That is exactly the kind of behavioral context annotations cannot 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?
Front-loads the payload contents, then the important address caveat, then the endpoint mapping. The enumerated content list is slightly long but each clause maps to real record sections, and no sentence is 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 an output schema present the return shape need not be restated, and the description covers scope, the data-gap gotcha, and the underlying endpoint for a single-parameter read tool. 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?
There is one parameter with 100% schema description coverage, and the schema already says the id comes from search_stays and starts with prop_. The description adds nothing about the parameter, so the baseline 3 for high coverage applies.
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 ('Full record for one property') and enumerates what the record contains (beds by room, amenities, access/stairs, rules, policies, verification status), which clearly separates it from search_stays and the booking/messaging siblings. The mapping to GET /v1/properties/{id} removes any remaining ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is clear: it is the single-property detail fetch whose id comes from search_stays, and it adds an explicit instruction for how to answer when the exact address is requested. It does not name a when-not condition or a competing sibling, but none of the listed siblings is a real alternative for this lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Itemized, binding price for exact dates and party, after re-checking the host's live calendars. Valid 10 minutes. Returns house rules and an exact refund schedule to show the guest. Does not reserve the dates. Maps to POST /v1/properties/{id}/quotes.
| Name | Required | Description | Default |
|---|---|---|---|
| pets | No | Number of pets. Default 0. Service animals don't count. | |
| adults | Yes | Number of adults (at least 1). | |
| infants | No | Number of infants under 2. Default 0. | |
| check_in | Yes | Arrival date, YYYY-MM-DD. | |
| children | No | Number of children aged 2 to 12. Default 0. | |
| check_out | Yes | Departure date, YYYY-MM-DD. | |
| property_id | Yes | The property's id, from search_stays. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| total | No | An amount in cents with its currency. |
| nights | No | |
| payment | No | |
| check_in | No | |
| check_out | No | |
| expires_at | No | |
| line_items | No | |
| house_rules | No | |
| property_id | No | |
| booking_mode | No | |
| refund_schedule | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description adds genuinely useful traits: a 10-minute validity window, that it returns house rules and a refund schedule, and that it does not hold the dates. These are the facts an agent needs before quoting a guest. It does not mention rate limits or what happens if the calendar re-check fails.
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 short sentences, each carrying distinct information, with the core purpose front-loaded. The trailing API mapping is compact and does not crowd out the important behavioral facts.
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 read-only quote tool with an output schema already present, the description covers purpose, freshness, validity window, what is returned, and the crucial non-reservation caveat. Nothing an agent needs to call it or set guest expectations 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 description coverage is 100%, so every parameter (property_id, dates, adults, children, infants, pets) is already documented in the schema. The description adds only the high-level notion of 'party' and 'exact dates' without new parameter-level meaning, so the baseline 3 applies.
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 ('Itemized, binding price') with the exact scoping ('for exact dates and party'), which cleanly separates it from check_availability (availability only) and request_booking (which reserves). An agent can route correctly 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 clear context: it re-checks the host's live calendars, so it is the pricing step after availability, and 'Does not reserve the dates' implies the follow-up is a booking request. It stops short of naming request_booking as the alternative, so the when-to-use guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request a stay from a quote. Set house_rules_accepted only after the guest has seen and agreed to the quote's house_rules. If the quote's payment.collected_by is "threshold", the booking starts as awaiting_payment and the response includes payment_url: the guest must open payment_url and add a card within 60 minutes, after which the host gets the request (status pending_host_confirmation). Otherwise the request goes to the host immediately and the host arranges payment after accepting. Returns the booking and a status link to give the guest; poll get_booking for changes.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The guest's email: confirmations, the payment link and the host's messages go there. | ||
| phone | No | The guest's phone number in international format, e.g. +15551234567. Optional. | |
| quote_id | Yes | The quote being booked, from get_quote (starts with quo_). | |
| last_name | Yes | The guest's last name. | |
| first_name | Yes | The guest's first name. | |
| special_requests | No | Anything the guest wants the host to know, in their words (arrival time, a question). Optional, up to 500 characters. | |
| house_rules_accepted | Yes | True only after the guest has seen and agreed to the quote's house_rules. |
| Name | Required | Description |
|---|---|---|
| booking | No | The booking. |
| payment_url | No | When present, the guest opens this to add a card; the request reaches the host only after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare this is a non-destructive open-world write; the description goes far beyond that by disclosing two distinct post-call state machines (awaiting_payment → pending_host_confirmation, or straight to host), the hard 60-minute card window, the payment_url hand-off obligation, and who collects payment in each branch.
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 action, then the consent rule, then the conditional payment path, then the return/polling note. Every sentence carries operational information; nothing is repeated from the schema or annotations.
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 7-param booking mutation with an output schema, the description covers the precondition, the divergent async flows, the guest-facing deadline, and the polling tool for status changes. Nothing an agent needs to call it correctly or set expectations downstream 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 most parameter meaning is already structured (email routing, phone format, quote_id prefix, special_requests length). The description still adds real semantics for the trickiest field, house_rules_accepted: it must only be true after the guest has reviewed and agreed to the quote's house_rules, which is an ordering constraint the schema alone does 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?
States a specific verb+resource ('Request a stay from a quote') and scopes it to a quote object, which cleanly separates it from get_quote, check_availability, and search_stays. An agent can pick this tool 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 preconditions (must come from a quote; house_rules_accepted only after the guest has seen and agreed to the rules) and names the follow-up alternative: 'poll get_booking for changes' rather than re-calling this tool. It even branches usage on quote state (payment.collected_by == 'threshold' vs. otherwise).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find verified independent vacation rentals. Filters are strict: every listed amenity must be present. With dates, results include a cached availability signal and an indicative all-in total (no guest service fee). Maps to GET /v1/search.
| Name | Required | Description | Default |
|---|---|---|---|
| pets | No | Number of pets. Only places that allow that many are returned. Service animals don't count as pets. | |
| limit | No | Most results to return, 1 to 50. Default 8. | |
| place | No | Town and state/country, e.g. 'Asheville, NC'. Use near_lat/near_lng instead when you have coordinates. | |
| adults | No | Number of adults. Default 2. | |
| infants | No | Number of infants under 2. | |
| check_in | No | Arrival date, YYYY-MM-DD. With check_out, only places free for the whole stay are returned, with an indicative total. | |
| children | No | Number of children aged 2 to 12. | |
| near_lat | No | Latitude to search around, with near_lng. Use instead of place when you have coordinates. | |
| near_lng | No | Longitude to search around, with near_lat. | |
| amenities | No | Amenity codes, e.g. hot_tub, wifi, ev_charger, dedicated_workspace, pool, fireplace_wood. | |
| check_out | No | Departure date, YYYY-MM-DD (the morning the guests leave). | |
| radius_km | No | How far from near_lat/near_lng to search, in kilometres. Default 30. | |
| instant_only | No | True to return only places that confirm instantly, without waiting for the host. | |
| min_bedrooms | No | Fewest bedrooms the place must have. | |
| max_total_usd | No | Maximum all-in total in dollars. Requires dates. | |
| min_wifi_mbps | No | Lowest Wi-Fi download speed needed, in megabits per second. | |
| step_free_entrance | No | True to return only places with a step-free way in. |
| Name | Required | Description |
|---|---|---|
| results | No | |
| next_cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, closed-world behavior, yet the description adds real context: amenity filters are conjunctive, and supplying dates yields a cached (not live) availability signal plus an indicative all-in total excluding guest service fees. That 'cached'/'indicative' qualifier is exactly the kind of caveat an agent needs and is not in 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?
Three short sentences, front-loaded with purpose, then the two highest-value behavioral facts (strict amenity matching, date-driven signals). Nothing is padded; even the endpoint mapping is a single clause.
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 not owed. For a 17-parameter, zero-required search tool the description covers purpose, filter strictness and date behavior adequately, though it omits any note on empty-result behavior or how limit/pagination affects result shaping.
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 semantics the schema lacks: every listed amenity must be present (AND, not OR), and the interaction between dates and the returned total/availability signal. It does not, however, clarify priority between place and near_lat/near_lng or radius behavior beyond what the schema states.
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 ('Find verified independent vacation rentals') and the word 'search' plus 'verified independent' distinguishes it from the single-property sibling get_property. It never names a sibling or explicitly contrasts with check_availability/get_quote, so it stops short of full 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?
Usage is implied by the search framing and by 'With dates, results include a cached availability signal', which hints when date filters are worthwhile. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as check_availability or get_property.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to the host on the guest's behalf, e.g. a question about check-in or a late arrival. Only send what the guest asked you to say. The host is emailed and replies appear in get_messages. Open from the request until two weeks after check-out.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The message to the host, in the guest's words, up to 2,000 characters. | |
| booking_id | Yes | The booking the message is about. | |
| guest_email | No | The email the booking was made with. Needed unless you connect with an agent token. |
| Name | Required | Description |
|---|---|---|
| message | No | The message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the side effect that the host is emailed and that replies surface via get_messages, plus the lifespan of the channel. That is genuinely useful behavioral context an agent cannot get from the structured fields, though it says nothing about delivery failure or rate limiting.
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?
Three short sentences, front-loaded with the purpose and ending with the channel's lifetime; each sentence carries distinct information. The window phrasing ('Open from the request until two weeks after check-out') is slightly terse but not wasteful.
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, return values need not be explained, and the description still usefully says where replies appear. Combined with annotations covering the safety profile, the only real hole is the unresolved distinction from ask_host.
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 booking_id, body and guest_email are already documented in the schema, and the baseline is 3. The description only reinforces the 'in the guest's words' intent for body and adds no syntax, format or conditional requirements 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+resource ('Send a message to the host') and adds concrete examples (check-in question, late arrival), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the sibling 'ask_host', whose name implies a highly similar action, and that overlap is left unresolved.
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 a content constraint ('Only send what the guest asked you to say') and an availability window ('Open from the request until two weeks after check-out'), which are real usage conditions. But it never states when to pick this over ask_host or how to handle a guest who wants something broader, so routing between the two messaging siblings 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
ask_host3 fields changedInput schema / properties / property_id / descriptionAdded value: +"The property the question is about."Input schema / properties / question / descriptionAdded value: +"The guest's question, in plain words, up to 500 characters. The host's answer may be added to the listing's FAQ."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The question as passed to the host, and an answer if the listing already has one.",
+ "properties": {
+ "answer": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}cancel_booking4 fields changedInput schema / properties / booking_id / descriptionAdded value: +"The booking or request to cancel."Input schema / properties / confirm / descriptionAdded value: +"False to preview the refund without changing anything; true to cancel."Input schema / properties / guest_email / descriptionAdded value: +"The email the booking was made with. Needed unless you connect with an agent token."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "With confirm=false, what the guest would get back if they cancelled now; with confirm=true, the cancelled booking and the refund.",
+ "properties": {
+ "booking": {
+ "type": "object"
+ },
+ "refund": {
+ "description": "An amount in cents with its currency.",
+ "properties": {
+ "amount": {
+ "type": "integer"
+ },
+ "currency": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+}check_availability3 fields changedInput schema / properties / from / descriptionAdded value: +"First night to check, YYYY-MM-DD."Input schema / properties / property_id / descriptionAdded value: +"The property's id, from search_stays."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Night-by-night availability.",
+ "properties": {
+ "days": {
+ "items": {
+ "additionalProperties": true,
+ "description": "One night.",
+ "properties": {
+ "available": {
+ "type": "boolean"
+ },
+ "date": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "property_id": {
+ "type": "string"
+ },
+ "timezone": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}get_booking2 fields changedInput schema / properties / booking_id / descriptionAdded value: +"The booking's id, from request_booking (starts with bkg_)."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The booking.",
+ "properties": {
+ "check_in": {
+ "type": "string"
+ },
+ "check_out": {
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "property_id": {
+ "type": "string"
+ },
+ "status": {
+ "description": "e.g. awaiting_payment, pending_host_confirmation, confirmed, declined, cancelled.",
+ "type": "string"
+ },
+ "total": {
+ "description": "An amount in cents with its currency.",
+ "properties": {
+ "amount": {
+ "type": "integer"
+ },
+ "currency": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+}get_messages3 fields changedInput schema / properties / booking_id / descriptionAdded value: +"The booking's id, from request_booking (starts with bkg_)."Input schema / properties / guest_email / descriptionAdded value: +"The email the booking was made with. Needed unless you connect with an agent token."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The conversation with the host, oldest first.",
+ "properties": {
+ "messages": {
+ "items": {
+ "additionalProperties": true,
+ "description": "One message.",
+ "properties": {
+ "body": {
+ "type": "string"
+ },
+ "from": {
+ "description": "guest or host",
+ "type": "string"
+ },
+ "sent_at": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+}get_property2 fields changedInput schema / properties / property_id / descriptionAdded value: +"The property's id, from search_stays (starts with prop_)."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Everything public about one place: description, rooms and beds, amenities, access, rules, policies, photos and the host's answers to common questions.",
+ "properties": {
+ "amenities": {
+ "type": "array"
+ },
+ "capacity": {
+ "type": "object"
+ },
+ "faq": {
+ "type": "array"
+ },
+ "id": {
+ "type": "string"
+ },
+ "listing": {
+ "type": "object"
+ },
+ "location": {
+ "type": "object"
+ },
+ "policies": {
+ "type": "object"
+ },
+ "rules": {
+ "type": "object"
+ }
+ },
+ "type": "object"
+}get_quote8 fields changedInput schema / properties / adults / descriptionAdded value: +"Number of adults (at least 1)."Input schema / properties / check_in / descriptionAdded value: +"Arrival date, YYYY-MM-DD."Input schema / properties / check_out / descriptionAdded value: +"Departure date, YYYY-MM-DD."Input schema / properties / children / descriptionAdded value: +"Number of children aged 2 to 12. Default 0."Input schema / properties / infants / descriptionAdded value: +"Number of infants under 2. Default 0."Input schema / properties / pets / descriptionAdded value: +"Number of pets. Default 0. Service animals don't count."Input schema / properties / property_id / descriptionAdded value: +"The property's id, from search_stays."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "A binding price for the stay, valid until expires_at.",
+ "properties": {
+ "booking_mode": {
+ "type": "string"
+ },
+ "check_in": {
+ "type": "string"
+ },
+ "check_out": {
+ "type": "string"
+ },
+ "expires_at": {
+ "type": "string"
+ },
+ "house_rules": {
+ "type": "array"
+ },
+ "id": {
+ "type": "string"
+ },
+ "line_items": {
+ "type": "array"
+ },
+ "nights": {
+ "type": "integer"
+ },
+ "payment": {
+ "type": "object"
+ },
+ "property_id": {
+ "type": "string"
+ },
+ "refund_schedule": {
+ "type": "array"
+ },
+ "total": {
+ "description": "An amount in cents with its currency.",
+ "properties": {
+ "amount": {
+ "type": "integer"
+ },
+ "currency": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+}request_booking8 fields changedInput schema / properties / email / descriptionAdded value: +"The guest's email: confirmations, the payment link and the host's messages go there."Input schema / properties / first_name / descriptionAdded value: +"The guest's first name."Input schema / properties / house_rules_accepted / descriptionAdded value: +"True only after the guest has seen and agreed to the quote's house_rules."Input schema / properties / last_name / descriptionAdded value: +"The guest's last name."Input schema / properties / phone / descriptionAdded value: +"The guest's phone number in international format, e.g. +15551234567. Optional."Input schema / properties / quote_id / descriptionAdded value: +"The quote being booked, from get_quote (starts with quo_)."Input schema / properties / special_requests / descriptionAdded value: +"Anything the guest wants the host to know, in their words (arrival time, a question). Optional, up to 500 characters."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "A booking or booking request.",
+ "properties": {
+ "booking": {
+ "additionalProperties": true,
+ "description": "The booking.",
+ "properties": {
+ "check_in": {
+ "type": "string"
+ },
+ "check_out": {
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "property_id": {
+ "type": "string"
+ },
+ "status": {
+ "description": "e.g. awaiting_payment, pending_host_confirmation, confirmed, declined, cancelled.",
+ "type": "string"
+ },
+ "total": {
+ "description": "An amount in cents with its currency.",
+ "properties": {
+ "amount": {
+ "type": "integer"
+ },
+ "currency": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "payment_url": {
+ "description": "When present, the guest opens this to add a card; the request reaches the host only after that.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}search_stays16 fields changedInput schema / properties / adults / descriptionAdded value: +"Number of adults. Default 2."Input schema / properties / check_in / descriptionAdded value: +"Arrival date, YYYY-MM-DD. With check_out, only places free for the whole stay are returned, with an indicative total."Input schema / properties / check_out / descriptionAdded value: +"Departure date, YYYY-MM-DD (the morning the guests leave)."Input schema / properties / children / descriptionAdded value: +"Number of children aged 2 to 12."Input schema / properties / infants / descriptionAdded value: +"Number of infants under 2."Input schema / properties / instant_only / descriptionAdded value: +"True to return only places that confirm instantly, without waiting for the host."Input schema / properties / limit / descriptionAdded value: +"Most results to return, 1 to 50. Default 8."Input schema / properties / min_bedrooms / descriptionAdded value: +"Fewest bedrooms the place must have."Input schema / properties / min_wifi_mbps / descriptionAdded value: +"Lowest Wi-Fi download speed needed, in megabits per second."Input schema / properties / near_lat / descriptionAdded value: +"Latitude to search around, with near_lng. Use instead of place when you have coordinates."Input schema / properties / near_lng / descriptionAdded value: +"Longitude to search around, with near_lat."Input schema / properties / pets / descriptionAdded value: +"Number of pets. Only places that allow that many are returned. Service animals don't count as pets."Input schema / properties / radius_km / defaultPrevious value: -25New value: +30Input schema / properties / radius_km / descriptionAdded value: +"How far from near_lat/near_lng to search, in kilometres. Default 30."Input schema / properties / step_free_entrance / descriptionAdded value: +"True to return only places with a step-free way in."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Matching places, best match first.",
+ "properties": {
+ "next_cursor": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "results": {
+ "items": {
+ "additionalProperties": true,
+ "description": "A place.",
+ "properties": {
+ "bedrooms": {
+ "type": "integer"
+ },
+ "booking_mode": {
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "indicative_total": {
+ "description": "An amount in cents with its currency.",
+ "properties": {
+ "amount": {
+ "type": "integer"
+ },
+ "currency": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "locality": {
+ "type": "string"
+ },
+ "max_guests": {
+ "type": "integer"
+ },
+ "region": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ },
+ "verified": {
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+}send_message4 fields changedInput schema / properties / body / descriptionAdded value: +"The message to the host, in the guest's words, up to 2,000 characters."Input schema / properties / booking_id / descriptionAdded value: +"The booking the message is about."Input schema / properties / guest_email / descriptionAdded value: +"The email the booking was made with. Needed unless you connect with an agent token."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The message as sent.",
+ "properties": {
+ "message": {
+ "additionalProperties": true,
+ "description": "The message.",
+ "properties": {
+ "body": {
+ "type": "string"
+ },
+ "sent_at": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+}ask_hostcancel_bookingcheck_availabilityget_bookingget_messagesget_propertyget_quoterequest_bookingsearch_stayssend_messageFind vacation rentals, explore photos and property details, and open direct host booking links.
Search and request stays at independent hotels, B&Bs, guesthouses and vacation rentals, direct.
Book vacation rentals direct: search homes, check live availability, get a real total.
Find vacation rentals worldwide by describing the trip, check host prices and book direct.
Add one secure layer between your agents and this server.