search_available_businesses
Search the top 10 matching published businesses and check live availability with exact booking requirements. Requires vertical and matching params. Salon searches may omit offeringId to search each business's services. Returns bookable options, without reserving capacity.
Scope & access
Follow the credential fields below. Public discovery does not require a login; private booking operations require the indicated token.
This tool advertises idempotent behavior. If an idempotencyKey is specified, reuse it with identical arguments only when retrying that same intended action.
Parameters
These are the directory endpoint parameters. Business endpoints scope public discovery to the published business; owner calls still require businessId. Inspect tools/list on your endpoint for the exact schema.
queryRequiredquery: what the customer is looking for, e.g. "quiet guesthouse near the beach"
locationOptionalOptional city/country or latitude/longitude/radiusKm search area.
verticalRequiredRequired so params have one unambiguous booking model.
limitOptionallimit: maximum results, 1–10
paramsRequiredBooking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone.
Example call
Pass this object to the MCP client's callTool method. Replace placeholders with returned IDs, saved credentials and the customer's details; use future dates appropriate to their request.
{
"name": "search_available_businesses",
"arguments": {
"query": "guesthouse near the beach",
"vertical": "hotel",
"params": {
"checkIn": "2026-11-14",
"checkOut": "2026-11-16",
"adults": 2
}
}
}JSON schemas
Nested fields, formats, enums and constraints are included in the complete schemas. Successful data is returned in structuredContent. SDK input validation and domain errors use different error shapes.
Input schemaJSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "query: what the customer is looking for, e.g. \"quiet guesthouse near the beach\""
},
"location": {
"description": "Optional city/country or latitude/longitude/radiusKm search area.",
"anyOf": [
{
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "lat: latitude in decimal degrees, e.g. 7.2213"
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "lng: longitude in decimal degrees, e.g. 79.8406"
},
"radiusKm": {
"default": 25,
"description": "radiusKm: search radius in kilometres, e.g. 10",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 500
}
},
"required": [
"lat",
"lng"
]
},
{
"type": "object",
"properties": {
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "city: city name, e.g. \"Negombo\""
},
"country": {
"description": "country: optional ISO 3166-1 alpha-2 code, e.g. \"LK\"",
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"required": [
"city"
]
}
]
},
"vertical": {
"type": "string",
"enum": [
"hotel",
"restaurant",
"salon"
],
"description": "Required so params have one unambiguous booking model."
},
"limit": {
"default": 10,
"description": "limit: maximum results, 1–10",
"type": "integer",
"minimum": 1,
"maximum": 10
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Booking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone."
}
},
"required": [
"query",
"vertical",
"params"
]
}Output schemaJSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"businessId": {
"type": "string"
},
"name": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"optionId": {
"type": "string"
},
"offeringId": {
"type": "string"
},
"offeringName": {
"type": "string"
},
"start": {
"type": "string"
},
"end": {
"type": "string"
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"total": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"currency": {
"type": "string"
},
"formatted": {
"type": "string"
}
},
"required": [
"amountMinor",
"currency",
"formatted"
],
"additionalProperties": false
},
"priceIsFrom": {
"type": "boolean"
},
"bookingPageUrl": {
"type": "string"
}
},
"required": [
"optionId",
"offeringId",
"offeringName",
"start",
"end",
"params",
"total",
"priceIsFrom",
"bookingPageUrl"
],
"additionalProperties": false
}
}
},
"required": [
"businessId",
"name",
"options"
],
"additionalProperties": {}
}
},
"candidatesChecked": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"message": {
"type": "string"
}
},
"required": [
"results",
"candidatesChecked",
"message"
],
"additionalProperties": false
}Behavior annotationsMCP
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors & next steps
Check isError before reading a success response. Follow nextStep where supplied, and never treat a pending booking as confirmed. See Errors and retries and the booking lifecycle for recovery paths.
Back to all tools