Travel search: 1.3M hotels and apartments, owner homes, tours, flights, taxi, car rental.
Scored across 13 tools
Most tools target distinct resource+action pairs (search_/get_ for hotels, properties, vehicles, activities; separate check_availability vs check_vehicle_availability). The main overlap is between search_hotels and search_properties (both accommodation) and between search_vehicles and book_ground_transport's 'car_rental' mode, but the descriptions explicitly differentiate these (world catalogue vs host-listed inventory; search vs booking links), so an agent can mostly tell them apart.
Names follow a highly predictable snake_case verb_noun pattern: search_hotels/search_properties/search_vehicles/search_activities, get_hotel/get_property/get_vehicle/get_activity, check_availability/check_vehicle_availability, find_flights, book_ground_transport. partner_with_hotelscasa is the only mild deviation but still fits a verb-object convention.
13 tools is well-scoped for a multi-vertical travel platform spanning stays, cars, activities, flights and ground transport. Each tool earns its place with no obvious redundancy, landing comfortably in the ideal 3-15 range.
The surface covers the full search→detail→availability→booking-link lifecycle across accommodation, cars and activities, plus flights and partner signup. Minor gaps exist (no review lookup, no cancel/modify operations, booking only via external links), but core traveller workflows are covered and workable.
Ground transport on HotelsCasa, with the right link to start: "taxi" — order a taxi or transfer (pre-filled with origin, destination, passengers, luggage and time when given); the fare is set by the taxi company and shown before ordering. "shipment" — send a parcel, furniture, a move or freight in the city, across the country or internationally on the transport exchange: publish the job without a price and carriers make offers; the sender picks one. "car_rental" — rent a car from owners and rental fleets. These services are growing city by city; the page shows what is available where the traveller is. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City (taxi and car rental). | |
| lang | No | Language of the links: es, en, de, fr, it, pt, tr, ru, pl, no, lv, lt, et, fi, sr or bg. Default es. | |
| when | No | Taxi pickup time, ISO 8601 (YYYY-MM-DDTHH:MM). Omit for now. | |
| origin | No | Taxi pickup address or place. | |
| luggage | No | ||
| service | Yes | ||
| passengers | No | ||
| destination | No | Taxi destination address or place. | |
| pickup_date | No | Car rental pickup date YYYY-MM-DD. | |
| return_date | No | Car rental return date YYYY-MM-DD. | |
| shipment_scope | No | Shipment distance: same city, within the country, or abroad. |
| Name | Required | Description |
|---|---|---|
| tip | No | |
| url | No | |
| service | No | |
| how_it_works | No | |
| business_account | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond these: fare is set by the taxi company and shown before ordering, services grow city by city, and the crucial instruction to always provide the URL as a clickable link. This adds value without contradicting 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 longer than average but necessary to cover three distinct services. It is structured with quoted service names and a critical final instruction, front-loading the core purpose. Every sentence earns its place, though it could be slightly tightened without losing information.
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 has 11 parameters and an output schema, the description explains the main flows and the crucial link-display rule. It doesn't detail every parameter, but the schema covers the rest. It provides enough context for an agent to invoke it correctly across the three services.
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 73%, so the description supplements it. It clarifies which parameters apply to which service (e.g., origin, destination, passengers, luggage, and when are taxi-specific; pickup_date and return_date are car rental; shipment_scope for shipments) and explains that taxi orders can be pre-filled with given details. This adds meaning beyond the schema's sparse descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly names three services (taxi, shipment, car_rental) with specific verbs and resources, and clearly distinguishes them from sibling tools (e.g., find_flights) by focusing on ground transport. Each service has its own explanation, making the tool's purpose 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?
It provides clear context for when to use each service (e.g., taxi for ordering a taxi/transfer, shipment for sending parcels, car_rental for renting a car). However, it does not explicitly state when not to use this tool or name alternative tools, though the sibling names imply alternatives like find_flights for air travel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check availability and price for up to 10 properties on given dates. THIS is the tool that answers «is it free on my dates and what does it cost»: search_properties never does. Use the property_key from search_properties results, and call it as soon as the traveller gives dates — never search the web instead. For INSTANT objects returns available (true/false) and, when free, a price_breakdown. For ON_REQUEST objects returns available:null with a price_note and a booking_link to the enquiry form — this is NOT a failure, it is the normal path for most of the catalogue. Results include two kinds of properties. Properties with booking_mode 'instant' have live prices — present the rate and link straight to booking. Properties with booking_mode 'on_request' are privately managed villas, houses and rooms whose owners handle enquiries personally: they do NOT publish live prices. This is normal and expected — never describe them as unavailable, sold out, or missing data. Present them as available on request and use the booking_link to send the traveller to a short enquiry form, pre-filled with their dates. The owner replies personally.
Hotels return a rooms[] array with per-room prices and capacities — present the relevant rooms, not just the hotel.
When no dates are given, price_from is only an indicative minimum. Seasonal, weekend and holiday rates apply. Always ask the traveller for dates, then call check_availability. Prices are indicative and confirmed on the property page.
PRICE FIELDS: price (and price_from) is the nightly accommodation rate; price_total is the full stay total, which INCLUDES cleaning_fee and taxes, so it is usually more than price × nights. Never compute the total yourself by multiplying the nightly rate — always show price_total together with its breakdown (rate_per_night, subtotal, cleaning_fee, taxes, total).
LOYALTY BONUS: when a result includes loyalty_bonus, mention it. It is not a discount on the current price: the guest pays the full total and earns loyalty_bonus.amount € as credit for a future stay on HotelsCasa (1 € per night). Present it as credit for later, never as a reduction of this total.
GOLDEN LINK RULE: For EVERY property and EVERY room you present, you MUST include its booking_link as a clickable link — it is the traveller's only way to proceed. Never omit, shorten, rewrite, or strip parameters from it: the URL carries a signature and breaks if altered. Return it verbatim. Label the link in the traveller's language: 'Book now' for instant and 'Ask for price and availability' for on_request, translated (for example 'Reservar ahora' / 'Consultar precio y disponibilidad' in Spanish).
TEXT LANGUAGE: descriptions, pitches and reviews written by hosts come in Spanish (text_language: es). Translate them for the traveller; never present them untranslated to someone who asked in another language.
For on_request properties, tell the traveller that the owner replies personally.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the answer: es, en, de, fr, it, pt, tr or ru. Default es. | |
| items | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| locale | No | |
| message | No | |
| results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context: on_request objects return available:null as a normal path, instant vs on_request modes behave differently, hotels return a rooms[] array, price_total includes fees, booking links must not be altered, and loyalty_bonus is credit rather than a discount. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized into clear sections with uppercase headers and front-loaded core purpose. There is some redundancy, such as repeating that the owner replies personally and that on_request is not a failure, but most sentences carry a distinct behavioral rule. It earns its length given the complexity of the tool.
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 instant vs on_request properties, hotel room arrays, price breakdowns, loyalty bonuses, booking links, and language handling, the description is remarkably complete. The output schema exists, so return-value details do not need to be repeated. The only notable omissions are minor parameter details already present in the schema. The agent has enough context to invoke the tool correctly and present results appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 50%, the description compensates by explaining that items are capped at 10, property_key comes from search_properties results, dates are the trigger for a real price, and missing dates make price_from only indicative. However, the guests parameter is not mentioned at all, and lang is only implied through the text-language guidance. It adds strong semantics for the most important parameters but leaves a couple to 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 opens with a specific verb and object: 'Check availability and price for up to 10 properties on given dates.' It directly answers the traveler's question and explicitly distinguishes itself from search_properties, which 'never does' this. An agent can immediately tell what the tool does and how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: call it as soon as the traveler gives dates, never search the web instead, and use the property_key from search_properties results. It also states what to do when dates are missing — ask for dates and then call check_availability — and clarifies that on_request results are not failures. This strongly routes the agent to the correct workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check availability and total price of up to 10 cars for given pickup/return dates. Returns available (true/false), days, price_day and total_eur. Cars without a published rate return total_eur:null with a price_note — that is normal, not a failure.
CARS ON HOTELSCASA: cars from local rental companies (offered_by:"rental_company") and from private owners. Cars marked instant:true are confirmed immediately; the rest are confirmed after booking by the rental company or by the owner, who replies personally. A rental-company car with similar_model:true guarantees the class, not the exact model.
PRICE: price_day is the daily rate and total_eur the rental for the whole period. A car with price_day:null has NOT published a rate — that is normal and common, never call it unavailable or say the data is missing. Present it with its price_note and send the traveller to the booking_link to ask.
GOLDEN LINK RULE: every car you present MUST include its booking_link verbatim, as a clickable link — never omit it, shorten it or strip its parameters. It is the only way the traveller can proceed.
NEVER invent or reveal a phone number, an address or a licence plate: they are not in the data and are only shared through the booking flow. Coordinates are approximate on purpose (~200 m) — use them for "3 km from the centre", never as a pickup address.
| Name | Required | Description | Default |
|---|---|---|---|
| pickup_date | Yes | YYYY-MM-DD. | |
| return_date | Yes | YYYY-MM-DD. | |
| vehicle_ids | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| items | No | |
| message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the readOnly/idempotent annotations: it explains that null price_day/total_eur is normal and must not be reported as unavailable, distinguishes instant vs. owner-confirmed bookings, clarifies similar_model class guarantees, mandates verbatim booking_link, and forbids inventing phone/address/plate. This is unusually rich behavioral guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by clearly labelled PRICE and GOLDEN LINK RULE blocks, which is easy to scan. Minor redundancy: the 'null price is normal, not a failure' point is made twice, once in the intro and again in PRICE.
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?
Despite an output schema existing, the description explains the semantics of each returned field (available, days, price_day, total_eur, price_note, booking_link) plus booking-confirmation and privacy constraints. Nothing needed to call or interpret this 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 coverage is 67% and already documents the YYYY-MM-DD formats and maxItems 10. The description restates the 'up to 10 cars' cap and date framing but adds no new meaning about what vehicle_ids are or where to obtain them. Baseline 3 for a mostly self-documenting 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 ('check availability and total price of up to 10 cars') with explicit scope (pickup/return dates) and enumerates the returned fields. It is clearly distinct from generic siblings like check_availability, though it never names a sibling to route against.
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?
Implies the tool is used to price/verify a set of vehicle_ids before booking, and the GOLDEN LINK rule hints at the booking flow that follows, but there is no explicit 'use this when / not when' or named alternative (e.g. search_vehicles first). Usage context is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link to search and book flights on HotelsCasa. This tool does NOT return live fares: flight prices are searched by the traveller on the page. Returns the flight page for the destination when HotelsCasa has one (108 popular destinations in Europe and the Americas), otherwise the general flight search page, plus the IATA code. Tell the traveller to enter origin and dates on that page. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the page: es, en, de, fr, it, pt, tr, ru, pl, no or sv. Default es. | |
| destination | No | Destination city or IATA code, e.g. Rome, LIS, Buenos Aires. |
| Name | Required | Description |
|---|---|---|
| url | No | |
| iata | No | |
| note | No | |
| live_fares | No | |
| destination | No | |
| search_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (readOnly, idempotent, non-destructive) by disclosing critical behavioral traits: it does not return live fares, returns a page URL plus IATA code, only covers 108 destinations in Europe and the Americas, and mandates that the URL must be given as an unchanged clickable link because it is the only way to book. These details are not present in the annotations and are essential for the agent to set traveller expectations and handle the response correctly.
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 appropriately sized for the tool's complexity. It front-loads the core purpose in the first sentence, then clarifies a key limitation (no live fares), explains the return behavior, and ends with actionable instructions for the agent. Every sentence earns its place and there is no redundant or filler content. The structure is logical and easy to parse.
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 is complete for an agent to call this tool correctly. It covers what the tool returns (flight page or general search page, plus IATA code), the scope (108 destinations), what it does NOT return (live fares), and how the agent should present results (tell traveller to enter origin/dates, give clickable URL). The output schema exists and would detail the response structure, so the description need not repeat that. No critical information 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% – both 'lang' and 'destination' are fully described with types and examples (e.g., 'Rome, LIS, Buenos Aires'). The description adds minimal additional parameter meaning: it implies 'destination' determines which page is returned and that the page language may be controlled by 'lang', but these are already inferred from the schema. No new semantics beyond the schema are provided, so a baseline score of 3 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 clearly states the tool's function: 'Link to search and book flights on HotelsCasa.' It specifies that it returns a flight page URL (destination-specific or general) plus the IATA code, and explicitly distinguishes itself from live-fare tools by stating it does NOT return live fares. This sets it apart from sibling search tools for other categories (hotels, activities, vehicles). The verb 'find' and resource 'flights' are specific 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 clear context on when to use this tool (to obtain a flight search page) and a key limitation ('does NOT return live fares'), which serves as a when-not. It also instructs the agent to tell the traveller to enter origin and dates on the page and to always provide the URL as a clickable link. However, it does not explicitly name alternative tools for other categories or state conditions for choosing this over siblings, though the sibling list makes that implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details of one activity by activity_key: description, what is included, duration, cancellation, next available dates with prices, photos and the page url. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the answer and of the links: es, en, de, fr, it, pt, tr or ru. Default es. | |
| activity_key | Yes | activity_key returned by search_activities. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| photos | No | |
| message | No | |
| summary | No | |
| activity | No | |
| duration | No | |
| included | No | |
| next_dates | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds real behavioral value by requiring the agent to always return the page URL as an unchanged clickable link and explaining it is the only way to book or buy. 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?
Two compact sentences with no fill. The first sentence front-loads the tool's purpose and the full list of returned fields, while the second delivers the critical link-handling rule. Every clause earns its place.
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, two-parameter lookup with an output schema, the description is complete. It specifies what data the traveller receives and the essential delivery requirement about the URL. The schema plus output schema cover the remaining details, so nothing needed to call the 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?
Schema description coverage is 100%, so lang and activity_key are already fully documented in the schema. The description only reinforces that activity_key selects a single activity, adding marginal semantic value beyond the schema. Baseline 3 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?
States a specific verb and resource: 'Details of one activity by activity_key' and enumerates the exact content returned (description, inclusions, duration, cancellation, dates/prices, photos, page url). This makes the tool's role immediately clear and distinguishable from search_activities and sibling get_* 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 schema notes that activity_key comes from search_activities, which implies this tool is for retrieving details after a search. However, the description itself never explicitly says when to use this tool vs search_activities or other siblings, nor does it state exclusions. Usage is implied rather than clearly instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of one hotel from search_hotels by its hotel_key: address, description, amenities, photos, check-in/check-out times, places nearby, a summary of guest opinions and the page url. With check_in/check_out it also checks availability live and returns an availability block: available true/false for those dates, with the real price when a room is free. availability.checked false means the supplier did not answer — the price is a catalogue price for other dates, not a confirmation. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the answer and of the links: es, en, de, fr, it, pt, tr or ru. Default es. | |
| adults | No | ||
| check_in | No | YYYY-MM-DD. | |
| children | No | ||
| check_out | No | YYYY-MM-DD. | |
| hotel_key | Yes | hotel_key returned by search_hotels. | |
| nationality | No | Guest nationality, ISO-3166 alpha-2. | |
| children_ages | No | Ages of the children, comma separated, e.g. "4,9". |
| Name | Required | Description |
|---|---|---|
| error | No | |
| hotel | No | |
| nearby | No | |
| photos | No | |
| address | No | |
| message | No | |
| city_url | No | |
| amenities | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavior beyond annotations: the live availability check behavior, the meaning of availability.checked=false (supplier did not answer, catalogue price is not a confirmation), and the mandatory instruction to provide the traveler with clickable, unchanged URLs. This is meaningful behavioral context not available in structured data.
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 three sentences with no filler. It front-loads the core purpose, then adds the availability caveat, then the critical URL-formatting instruction. Every sentence carries operational weight, and the structure guides the agent from the primary function to edge-case semantics to user-facing obligations.
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 detail tool with an output schema, the description is complete: it explains the primary data returned, the conditional availability block with its failure semantics, and the required link-handling behavior. The output schema covers return structure, so nothing critical is missing for an agent to call and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents most parameters. The description adds meaning for hotel_key (returned by search_hotels) and check_in/check_out (triggers live availability block), but it does not add semantic value for lang, adults, children, nationality, or children_ages. This is a reasonable baseline score with modest added value.
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-plus-resource statement: 'Full details of one hotel from search_hotels by its hotel_key'. It enumerates the exact content fields (address, description, amenities, photos, check-in/check-out times, places nearby, guest opinions, page URL) and clearly distinguishes this tool from search_hotels, get_property, get_activity, and get_vehicle.
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 clearly implies the tool is used after search_hotels by requiring its hotel_key as input, and it explains that check_in/check_out enable live availability. It does not explicitly name alternatives or state when-not-to-use, but the 'from search_hotels by its hotel_key' phrasing gives enough contextual guidance for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details for one property by property_key (from search results): description, amenities, photos, house rules, cancellation, recent reviews (no names), and — when dates are given — a price_breakdown (INSTANT) or an availability_note (ON_REQUEST). Always includes booking_link. Results include two kinds of properties. Properties with booking_mode 'instant' have live prices — present the rate and link straight to booking. Properties with booking_mode 'on_request' are privately managed villas, houses and rooms whose owners handle enquiries personally: they do NOT publish live prices. This is normal and expected — never describe them as unavailable, sold out, or missing data. Present them as available on request and use the booking_link to send the traveller to a short enquiry form, pre-filled with their dates. The owner replies personally.
Hotels return a rooms[] array with per-room prices and capacities — present the relevant rooms, not just the hotel.
When no dates are given, price_from is only an indicative minimum. Seasonal, weekend and holiday rates apply. Always ask the traveller for dates, then call check_availability. Prices are indicative and confirmed on the property page.
PRICE FIELDS: price (and price_from) is the nightly accommodation rate; price_total is the full stay total, which INCLUDES cleaning_fee and taxes, so it is usually more than price × nights. Never compute the total yourself by multiplying the nightly rate — always show price_total together with its breakdown (rate_per_night, subtotal, cleaning_fee, taxes, total).
LOYALTY BONUS: when a result includes loyalty_bonus, mention it. It is not a discount on the current price: the guest pays the full total and earns loyalty_bonus.amount € as credit for a future stay on HotelsCasa (1 € per night). Present it as credit for later, never as a reduction of this total.
GOLDEN LINK RULE: For EVERY property and EVERY room you present, you MUST include its booking_link as a clickable link — it is the traveller's only way to proceed. Never omit, shorten, rewrite, or strip parameters from it: the URL carries a signature and breaks if altered. Return it verbatim. Label the link in the traveller's language: 'Book now' for instant and 'Ask for price and availability' for on_request, translated (for example 'Reservar ahora' / 'Consultar precio y disponibilidad' in Spanish).
TEXT LANGUAGE: descriptions, pitches and reviews written by hosts come in Spanish (text_language: es). Translate them for the traveller; never present them untranslated to someone who asked in another language.
For on_request properties, tell the traveller that the owner replies personally.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the answer: es, en, de, fr, it, pt, tr or ru. Default es. | |
| guests | No | ||
| check_in | No | YYYY-MM-DD. | |
| check_out | No | YYYY-MM-DD. | |
| property_key | Yes | The property_key returned by search_properties. |
| Name | Required | Description |
|---|---|---|
| lat | No | |
| lng | No | |
| city | No | |
| name | No | |
| type | No | |
| error | No | |
| rooms | No | |
| photos | No | |
| rating | No | |
| region | No | |
| country | No | |
| message | No | |
| reviews | No | |
| bedrooms | No | |
| amenities | No | |
| available | No | |
| bathrooms | No | |
| max_guests | No | |
| price_from | No | |
| price_note | No | |
| description | No | |
| price_total | No | |
| short_pitch | No | |
| booking_link | No | |
| booking_mode | No | |
| cancellation | No | |
| property_key | No | |
| property_type | No | |
| reviews_count | No | |
| text_language | No | |
| thumbnail_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing the two property types, the obligation to present on_request as available, the golden booking_link rule, the loyalty bonus mechanics, price field semantics, and the need to translate text. It also includes negative instructions (e.g., never compute totals, never strip link parameters). This is rich, transparent behavior disclosure with no contradictions.
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 well-structured with clear headings (PRICE FIELDS, LOYALTY BONUS, GOLDEN LINK RULE, TEXT LANGUAGE) and front-loaded purpose. While some repetition exists (e.g., 'never describe them as unavailable' appears twice), every section conveys essential operational rules. It is arguably longer than ideal but remains organized and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers return content, pricing behavior, booking links, language handling, and edge cases (no dates, on_request). It explains the difference between indicative and confirmed prices, and it references an output schema. No critical operational detail is missing for an agent to correctly present property information.
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 80%, with descriptions for lang, check_in, check_out, and property_key; guests lacks a description. The description adds meaning by explaining that check_in/check_out enable price_breakdown or availability_note, and that without dates price_from is only indicative. It also clarifies property_key's origin. This adds value beyond the schema, though it doesn't elaborate on the guests parameter's purpose.
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 ('get') and resource ('property'), and clearly defines the output: full details for one property by property_key, including description, amenities, photos, house rules, cancellation, reviews, and pricing. It also distinguishes itself from search_properties (which returns search results) and check_availability (which is for availability checks), and it even addresses hotels within its scope. The purpose is unambiguous and differentiates well from siblings.
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 clear usage context: it is to be used after search_properties, and it instructs to call check_availability when dates are needed. It also explains how to handle on_request vs instant properties. However, it does not explicitly mention when to use get_hotel instead of get_property, despite hotels being covered here; this leaves a small ambiguity in sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of ONE rental car: photos, specs, rental conditions (deposit, km limit, fuel policy, minimum age, licence years, pets, cancellation) and busy_ranges — the dates already taken over the next six months. Use busy_ranges to propose alternative dates instead of telling the traveller the car is unavailable.
CARS ON HOTELSCASA: cars from local rental companies (offered_by:"rental_company") and from private owners. Cars marked instant:true are confirmed immediately; the rest are confirmed after booking by the rental company or by the owner, who replies personally. A rental-company car with similar_model:true guarantees the class, not the exact model.
PRICE: price_day is the daily rate and total_eur the rental for the whole period. A car with price_day:null has NOT published a rate — that is normal and common, never call it unavailable or say the data is missing. Present it with its price_note and send the traveller to the booking_link to ask.
GOLDEN LINK RULE: every car you present MUST include its booking_link verbatim, as a clickable link — never omit it, shorten it or strip its parameters. It is the only way the traveller can proceed.
NEVER invent or reveal a phone number, an address or a licence plate: they are not in the data and are only shared through the booking flow. Coordinates are approximate on purpose (~200 m) — use them for "3 km from the centre", never as a pickup address.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the answer: es, en, de, fr, it, pt, tr or ru. Default es. | |
| vehicle_id | Yes | The vehicle_id returned by search_vehicles. | |
| pickup_date | No | YYYY-MM-DD. | |
| return_date | No | YYYY-MM-DD. |
| Name | Required | Description |
|---|---|---|
| city | No | |
| days | No | |
| fuel | No | |
| make | No | |
| name | No | |
| class | No | |
| error | No | |
| model | No | |
| seats | No | |
| photos | No | |
| country | No | |
| instant | No | |
| message | No | |
| available | No | |
| price_day | No | |
| total_eur | No | |
| conditions | No | |
| price_note | No | |
| vehicle_id | No | |
| busy_ranges | No | |
| description | No | |
| booking_link | No | |
| transmission | No | |
| thumbnail_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safe-read profile; the description adds substantial behavioral context beyond them — car origin (rental company vs private owner), instant:true immediate confirmation, similar_model class guarantees, the golden-link requirement, and explicit prohibitions on inventing phone numbers, addresses or licence plates, plus approximate coordinates. This is exactly the extra layer that annotations cannot carry.
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?
Organized into labelled blocks (CARS ON HOTELSCASA, PRICE, GOLDEN LINK RULE, NEVER) with the core purpose front-loaded. Dense but every block maps to a real decision the agent must make; slightly long, though nothing reads as 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 and annotations covering safety, the description supplies the remaining decision-critical detail: pricing edge cases, booking-confirmation semantics, link-mandate, and privacy constraints. An agent has everything needed to present and route a car correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so vehicle_id, lang, pickup_date and return_date are already documented in the schema. The description adds meaning to output fields (busy_ranges, price_day, price_note) rather than to the inputs, so it doesn't extend parameter semantics beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: 'Full details of ONE rental car', then enumerates exactly what is returned (photos, specs, rental conditions, busy_ranges). The 'ONE' and the vehicle_id-by-search_vehicles linkage cleanly separate it from search_vehicles.
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 concrete operational guidance: use busy_ranges to propose alternative dates rather than declaring unavailability, and route price_day:null cars to booking_link via price_note. It never explicitly contrasts with siblings like check_vehicle_availability, but the usage context is clear enough to act on.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For businesses and professionals who want to WORK with HotelsCasa (not for travellers). HotelsCasa invites and is actively looking for: taxi fleet owners and independent taxi drivers, van and truck carriers and transport companies, car rental fleets and private car owners, companies that ship goods regularly, and owners of holiday homes, apartments and hotels. Returns, for the chosen profile (or all), what HotelsCasa offers and the page where they sign up. Use it whenever someone asks how to join, list, register a fleet or get orders. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the links: es, en, de, fr, it, pt, tr, ru, pl, no, lv, lt, et, fi, sr or bg. Default es. | |
| profile | No |
| Name | Required | Description |
|---|---|---|
| url | No | |
| who | No | |
| more | No | |
| offer | No | |
| profile | No | |
| profiles | No | |
| all_programmes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint, idempotentHint, and destructveHint false. The description adds that the tool only returns offers and sign-up pages rather than performing registration, and includes an important output instruction about giving URLs as unchanged clickable links. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but verbose: the long list of partner categories is relevant, yet phrasing like 'HotelsCasa invites and is actively looking for' adds padding. The final traveller URL instruction is useful but the overall structure is less crisp than it could be.
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 reference tool with an output schema and annotations covering safety, the description provides the essential selection context: audience, triggering queries, result content, and URL presentation behavior. Minor confusion from the word 'traveller' in the output instruction does not create a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes lang and provides a profile enum, but the description adds human-readable meaning by enumerating the partner categories and explaining that a selected profile or 'all' controls the returned offers. This compensates for the 50% schema_description_cverage and helps an agent map user intent to profile values.
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 identifies the tool as being for businesses and professionals who want to work with HotelsCasa, not for travellers, and states it returns what HotelsCasa offers plus the sign-up page for a chosen profile. This differentiates it from traveller-facing sibling tools like search_hotels and book_ground_transport.
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 explicitly says to use the tool whenever someone asks how to join, list, register a fleet, or get orders, and explicitly excludes travellers. It does not name alternative sibling tools for traveller bookings, but the when/when-not guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search tickets, tours and attractions (museums, monuments, day trips) sold on HotelsCasa with our partner Tiqets. Search by city (its name in any language works: Istanbul, İstanbul, Estambul, Стамбул), by ISO country code or by text. With no arguments returns the cities with the most activities. The answer carries total (how many activities match in all), count (how many are on this page, 10 at most) and matched_cities when a city was recognised. Prices are per person in EUR, "from". Tickets are bought on the activity page. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name in any language, e.g. Istanbul, Стамбул, Rome, Roma. | |
| lang | No | Language of the answer and of the links: es, en, de, fr, it, pt, tr or ru. Default es. | |
| page | No | ||
| sort | No | ||
| limit | No | How many results to return (1-10, default 10). | |
| query | No | Text in the title, e.g. Sagrada Familia, Colosseum. | |
| country | No | ISO-3166 alpha-2, e.g. TR, IT, BR. Can be combined with city. |
| Name | Required | Description |
|---|---|---|
| page | No | |
| count | No | |
| error | No | |
| items | No | |
| total | No | |
| cities | No | |
| message | No | |
| next_page | No | |
| matched_cities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only, idempotent, non-destructive and closed-world. The description goes beyond them with real operational context: page size cap of 10, price unit and currency ('per person in EUR, from'), and the critical booking constraint that tickets are purchased on the activity page so the URL must be passed through unchanged. It does not discuss rate limits or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what is searched and where, then filtering modes, then the empty-argument behavior, then response and pricing notes, ending on the booking constraint. Dense but every sentence carries information an agent needs to call or report correctly.
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-parameter, open-search tool with an output schema, the description covers filtering modes, defaults, pagination cap, response fields, currency semantics, and the downstream booking workflow. Nothing an agent needs to invoke it or handle its results is missing, and return-value detail is largely delegated to the output schema as expected.
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 71%, above the baseline where the schema carries most weight. The description groups the filtering modes (city/country/text) and notes multilingual city input, but adds little beyond the schema's own city example, and leaves 'page' and 'sort' semantics entirely to 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 names a specific verb and resource ('Search tickets, tours and attractions... sold on HotelsCasa with our partner Tiqets') and scopes it in a way that separates it from siblings like search_hotels, search_properties and get_activity. The supplier and inventory relationship adds precision a generic 'search' would lack.
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 selection conditions – search by city name (any language), ISO country code, or free text – and defines the no-argument fallback (cities with the most activities). It stops short of explicitly contrasting itself with get_activity (detail lookup) or naming when NOT to call it, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search hotels on HotelsCasa: hotels, apartments, guest houses and holiday homes that can actually be booked, in 77 countries — Europe, Turkey, Russia and Ukraine, the Caucasus, Central Asia, and the whole of Latin America including Mexico, Central America and the Caribbean. Search by city (English or local name; add country to disambiguate) or by lat/lng + radius_km. Country alone returns its main cities to choose from. Each item has stars, guest rating (out of 10), photo, price and the url of the hotel page. WITH DATES (check_in + check_out): availability is checked LIVE with the supplier before answering. Every item returned has a room actually free for those dates, and carries available:true, price_eur_per_night, price_total_eur, nights, board and refundable. Show price_total_eur for the stay together with the nightly rate, and say the price was checked for those dates. An empty list with availability_checked:true means there really is nothing free for those dates — say so and offer other dates or a wider radius. If availability_checked is false, the supplier did not answer: the prices are catalogue prices for OTHER dates — never present them as a confirmation. WITHOUT DATES: price_from_eur_per_night is an indicative starting price per night; show it as "from EUR X per night" and confirm on the page. Pass check_in/check_out/adults (and children_ages when children travel) to get real, bookable prices. Always give the traveller the url of every item as a clickable link, unchanged: it is the only way to book or buy.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | ||
| lng | No | ||
| city | No | City name in English, e.g. Rome, Lisbon, Munich, Buenos Aires. | |
| lang | No | Language of the answer and of the links: es, en, de, fr, it, pt, tr or ru. Default es. | |
| page | No | ||
| sort | No | ||
| type | No | Accommodation type: apartments, aparthotels, guest houses, holiday homes, rural houses, villas. | |
| limit | No | How many results to return (1-10, default 10). | |
| query | No | Part of the hotel name (with city or lat/lng), or a city name. | |
| rooms | No | How many rooms for the same stay (default 1). | |
| adults | No | ||
| country | No | ISO-3166 alpha-2 country code, e.g. FR, IT, AR. | |
| check_in | No | YYYY-MM-DD. | |
| children | No | ||
| check_out | No | YYYY-MM-DD. | |
| price_max | No | Max EUR per night. With dates it is applied to the live price for those dates; without dates, to the catalogue price. | |
| price_min | No | Min EUR per night. Same rule as price_max. | |
| radius_km | No | Radius for lat/lng search, default 10, max 50. | |
| stars_min | No | ||
| nationality | No | Guest nationality, ISO-3166 alpha-2. Affects the rate; taken from the traveller IP when omitted. | |
| children_ages | No | Ages of the children, comma separated, e.g. "4,9". The supplier prices a child by age; without this, 8 years is assumed. |
| Name | Required | Description |
|---|---|---|
| city | No | |
| page | No | |
| count | No | |
| error | No | |
| items | No | |
| cities | No | |
| message | No | |
| next_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by explaining live supplier availability checks, the meaning of availability_checked true/false, how to present prices in both dated and dateless modes, and the requirement to return unchanged clickable URLs. It also warns against presenting catalogue prices as confirmations. This rich operational context is exactly what an agent needs and complements the readOnly/idempotent hints without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: it front-loads the core purpose, then distinguishes dated vs dateless behavior, empty responses, supplier failure, and final booking requirements. The structure using WITH DATES/WITHOUT DATES is helpful for an agent scanning quickly. There is no filler or repetition that could be removed without losing important guidance.
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 has 21 optional parameters and an output schema, the description covers the complete decision space needed to call it correctly: search modes, parameter combinations, live availability semantics, error conditions, price presentation rules, and the mandatory URL handling. The presence of an output schema means return-value documentation is not needed in the description. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds essential meaning beyond the schema for key parameters: city searches may use English or local names with country disambiguation, lat/lng requires radius_km, check_in/check_out trigger live availability, and children_ages affects pricing. Schema coverage is 67%, so the schema still documents several parameters, but the description provides the critical behavioral logic around dates, countries, and radius. A small deduction because some parameters like lang, page, sort, and rooms are only covered by 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 a specific verb and resource: searching bookable hotel properties on HotelsCasa, and enumerates accommodation types and geographic scope. It also differentiates from siblings by emphasizing live availability checking with dates and required hotel page URLs, which is not claimed by sibling tools like search_properties or get_hotel. The purpose is unambiguous and actionable.
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 strong context for when to use the tool: searching hotels by city or coordinates, with and without dates, and when country-only queries should be used. It does not explicitly name alternatives or state when not to use this tool versus siblings, but the context is clear enough that an agent would not confuse it with flight, vehicle, or activity search. A small deduction for missing explicit sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the holiday homes, villas, rural houses and small hotels that private owners list directly on HotelsCasa (hotelscasa.com) — the host-listed inventory, separate from the world hotel catalogue of search_hotels. Search by location, dates, guests and filters. Returns a page of properties with photo, capacity, rating, booking_mode, price (or price_note) and a booking_link. Use lat/lng + radius_km for "near X" queries. Every result has a property_key. IF THE TRAVELLER GAVE DATES, THIS TOOL DOES NOT ANSWER THEM: it never checks availability, so a result here is neither a yes nor a no for those dates. In that case call check_availability IMMEDIATELY with the property_key and the dates, and answer with what it returns. Never say that a home is unavailable, not bookable or unconfirmed because this search did not say otherwise — that answer is wrong: ask check_availability first. For details of one home use get_property. Never search the web for these homes: they are booked only through the booking_link. Results include two kinds of properties. Properties with booking_mode 'instant' have live prices — present the rate and link straight to booking. Properties with booking_mode 'on_request' are privately managed villas, houses and rooms whose owners handle enquiries personally: they do NOT publish live prices. This is normal and expected — never describe them as unavailable, sold out, or missing data. Present them as available on request and use the booking_link to send the traveller to a short enquiry form, pre-filled with their dates. The owner replies personally.
Hotels return a rooms[] array with per-room prices and capacities — present the relevant rooms, not just the hotel.
When no dates are given, price_from is only an indicative minimum. Seasonal, weekend and holiday rates apply. Always ask the traveller for dates, then call check_availability. Prices are indicative and confirmed on the property page.
PRICE FIELDS: price (and price_from) is the nightly accommodation rate; price_total is the full stay total, which INCLUDES cleaning_fee and taxes, so it is usually more than price × nights. Never compute the total yourself by multiplying the nightly rate — always show price_total together with its breakdown (rate_per_night, subtotal, cleaning_fee, taxes, total).
LOYALTY BONUS: when a result includes loyalty_bonus, mention it. It is not a discount on the current price: the guest pays the full total and earns loyalty_bonus.amount € as credit for a future stay on HotelsCasa (1 € per night). Present it as credit for later, never as a reduction of this total.
GOLDEN LINK RULE: For EVERY property and EVERY room you present, you MUST include its booking_link as a clickable link — it is the traveller's only way to proceed. Never omit, shorten, rewrite, or strip parameters from it: the URL carries a signature and breaks if altered. Return it verbatim. Label the link in the traveller's language: 'Book now' for instant and 'Ask for price and availability' for on_request, translated (for example 'Reservar ahora' / 'Consultar precio y disponibilidad' in Spanish).
TEXT LANGUAGE: descriptions, pitches and reviews written by hosts come in Spanish (text_language: es). Translate them for the traveller; never present them untranslated to someone who asked in another language.
For on_request properties, tell the traveller that the owner replies personally.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude for radius search. | |
| lng | No | Longitude for radius search. | |
| city | No | ||
| lang | No | Language of the answer: es, en, de, fr, it, pt, tr or ru. Default es. | |
| limit | No | How many results to return (1-10, default 10). | |
| query | No | Free text (name or city). | |
| guests | No | ||
| region | No | Province/region. | |
| country | No | ISO-3166 alpha-2, e.g. ES. | |
| bedrooms | No | ||
| check_in | No | YYYY-MM-DD. | |
| bathrooms | No | ||
| check_out | No | YYYY-MM-DD. | |
| price_max | No | EUR/night. Same rule as price_min. | |
| price_min | No | EUR/night. Only constrains objects that publish a rate; on_request objects are always kept. | |
| radius_km | No | Search radius in km (default 15, max 100). | |
| page_token | No | Opaque token from a previous page. | |
| property_type | No |
| Name | Required | Description |
|---|---|---|
| page | No | |
| count | No | |
| error | No | |
| items | No | |
| locale | No | |
| message | No | |
| next_page_token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, and destructive=false, and the description adds substantial behavioral context beyond that: the tool never checks availability, on_request properties legitimately have no live prices, price_total includes fees and taxes, and booking_links must never be altered. This directly prevents common agent mistakes such as claiming a home is unavailable based on this search alone.
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 and dense, but it is front-loaded with the most critical distinction and the availability warning comes early. There is some repetition of the 'do not call this unavailable' rule, and the price and booking-mode guidance could be tightened slightly, but the length is largely justified by the number of failure modes it precludes.
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 search tool with an output schema, this description is remarkably complete: it covers scope, date-handling, availability handoff, booking modes, price fields, link integrity, language translation, and loyalty_bonus presentation. Nothing an agent needs in order to invoke the tool correctly and interpret its results 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?
With 72% schema coverage, the schema documents most parameters, and the description adds further meaning: lat/lng + radius_km is the mechanism for 'near X' queries, and price_min does not filter on_request objects. It does not walk through all 18 parameters, but the most safety-critical and output-affecting semantics are explained clearly.
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: it searches the host-listed holiday homes, villas, rural houses and small hotels on HotelsCasa. It also explicitly sets this apart from the world hotel catalogue of search_hotels, so an agent can tell the two sibling tools apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing rules: call check_availability immediately when dates are provided, use get_property for details of a single home, and never search the web for these homes. It also names search_hotels as the alternative for world hotel inventory, making the when-to-use decision unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search RENTAL CARS on HotelsCasa by city, country or geographic radius, with pickup/return dates, seats, transmission, class and price. Cars are a SEPARATE inventory from properties — use this tool only when the traveller asks about a car, never to answer an accommodation question.
CARS ON HOTELSCASA: cars from local rental companies (offered_by:"rental_company") and from private owners. Cars marked instant:true are confirmed immediately; the rest are confirmed after booking by the rental company or by the owner, who replies personally. A rental-company car with similar_model:true guarantees the class, not the exact model.
PRICE: price_day is the daily rate and total_eur the rental for the whole period. A car with price_day:null has NOT published a rate — that is normal and common, never call it unavailable or say the data is missing. Present it with its price_note and send the traveller to the booking_link to ask.
GOLDEN LINK RULE: every car you present MUST include its booking_link verbatim, as a clickable link — never omit it, shorten it or strip its parameters. It is the only way the traveller can proceed.
NEVER invent or reveal a phone number, an address or a licence plate: they are not in the data and are only shared through the booking flow. Coordinates are approximate on purpose (~200 m) — use them for "3 km from the centre", never as a pickup address.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude for radius search. | |
| lng | No | Longitude for radius search. | |
| city | No | ||
| lang | No | Language of the answer: es, en, de, fr, it, pt, tr or ru. Default es. | |
| class | No | Vehicle category slug (economy, compact, sedan, estate, suv, van, luxury, sports…). | |
| limit | No | How many results to return (1-10, default 10). | |
| query | No | Free text: make, model or city. | |
| country | No | ISO-3166 alpha-2, e.g. ES. | |
| price_max | No | EUR/day. Same rule as price_min. | |
| price_min | No | EUR/day. Cars without a published rate are always kept. | |
| radius_km | No | Search radius in km (default 15, max 100). | |
| seats_min | No | ||
| page_token | No | Opaque token from a previous page. | |
| pickup_date | No | YYYY-MM-DD. | |
| return_date | No | YYYY-MM-DD. | |
| transmission | No | 'manual' or 'automatic'. |
| Name | Required | Description |
|---|---|---|
| page | No | |
| count | No | |
| error | No | |
| items | No | |
| message | No | |
| next_page_token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: instant:true vs. owner-confirmed booking, similar_model guaranteeing class not model, price_day:null being normal rather than unavailable, the mandatory verbatim booking_link, and the prohibition on inventing phone/address/plate plus deliberately approximate coordinates.
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?
Long but front-loaded with purpose and exclusion before the labeled CARS/PRICE/GOLDEN LINK/NEVER blocks; each block carries operational rules an agent would otherwise get wrong. Some repetition (price rules restated in both prose and schema descriptions) slightly dilutes it.
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 16 optional parameters, an output schema, and full read-only annotations, the description supplies everything needed to call and present results correctly, including field-level interpretation (price_day vs total_eur) and the mandatory booking_link handling. Nothing material 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 88%, so the baseline is 3, but the description adds real semantics beyond the schema: price_min/price_max keep cars without a published rate, lat/lng drive the radius search, and radius_km/pickup_date/return_date are contextualized by the prose about rates and periods. It stops short of explaining page_token or query syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (RENTAL CARS) with the searchable dimensions listed (city, country, radius, dates, seats, transmission, class, price). It explicitly separates cars from properties, so an agent can distinguish it from search_properties/search_hotels without opening a 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 an explicit when ('traveller asks about a car') and when-not ('never to answer an accommodation question'), which routes the agent away from the accommodation siblings. The only minor gap is that it does not name search_properties/search_hotels verbatim, but the exclusion is unambiguous.
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.
search_vehicles1 field changedInput schema / properties / class / descriptionPrevious value: -"Vehicle category slug (economy, suv, van…)."New value: +"Vehicle category slug (economy, compact, sedan, estate, suv, van, luxury, sports…)."search_activities4 fields changedInput schema / properties / city / descriptionAdded value: +"City name in any language, e.g. Istanbul, Стамбул, Rome, Roma."Input schema / properties / country / descriptionPrevious value: -"ISO-3166 alpha-2, e.g. ES, IT."New value: +"ISO-3166 alpha-2, e.g. TR, IT, BR. Can be combined with city."Output schema / properties / matched_citiesAdded value: +{
+ "items": {
+ "additionalProperties": true,
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / totalAdded value: +{
+ "type": "integer"
+}get_hotel3 fields changedInput schema / properties / childrenAdded value: +{
+ "maximum": 4,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / children_agesAdded value: +{
+ "description": "Ages of the children, comma separated, e.g. \"4,9\".",
+ "type": "string"
+}Input schema / properties / nationalityAdded value: +{
+ "description": "Guest nationality, ISO-3166 alpha-2.",
+ "type": "string"
+}search_hotels5 fields changedInput schema / properties / children_agesAdded value: +{
+ "description": "Ages of the children, comma separated, e.g. \"4,9\". The supplier prices a child by age; without this, 8 years is assumed.",
+ "type": "string"
+}Input schema / properties / nationalityAdded value: +{
+ "description": "Guest nationality, ISO-3166 alpha-2. Affects the rate; taken from the traveller IP when omitted.",
+ "type": "string"
+}Input schema / properties / price_max / descriptionPrevious value: -"Max EUR per night. Only hotels with a published rate are kept."New value: +"Max EUR per night. With dates it is applied to the live price for those dates; without dates, to the catalogue price."Input schema / properties / price_minAdded value: +{
+ "description": "Min EUR per night. Same rule as price_max.",
+ "type": "number"
+}Input schema / properties / roomsAdded value: +{
+ "description": "How many rooms for the same stay (default 1).",
+ "maximum": 4,
+ "minimum": 1,
+ "type": "integer"
+}book_ground_transportcheck_availabilitycheck_vehicle_availabilityfind_flightsget_activityget_hotelget_propertyget_vehiclepartner_with_hotelscasasearch_activitiessearch_hotelssearch_propertiessearch_vehiclesSearch 650,000 hotels by place, vibe, photos and reviews. Search needs no key.
Search hotels & rentals: live prices & reviews across Booking.com, Airbnb, Vrbo & Google Hotels.
Search hotels and get hotel details. Search-only; book on hotely.travel.
Search and book flights and hotels: hundreds of airlines, plus bookable hotel rates.
Add one secure layer between your agents and this server.
