Discovery & availability

search_businesses

Searches published hotels, restaurants and salons by free-text query, location, type and optional date. Returns up to 10 businesses with price-from, distance and booking links. Results are not sponsored.

View as Markdown

Scope & access

Directory onlyRead only

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.

queryRequired

string

query: what the customer is looking for, e.g. "quiet guesthouse near the beach"

locationOptional

object | object

See the full schema below for constraints and nested fields.

verticalOptional

"hotel" | "restaurant" | "salon"

vertical: optional business type: hotel, restaurant or salon

dateOptional

string

date: optional local date to check availability for, YYYY-MM-DD, e.g. "2026-11-14"

partySizeOptional

integer

partySize: optional number of people (restaurants) or guests (hotels), e.g. 2

limitOptional

integer

limit: maximum results, 1–10

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.

search_businesses · MCP client arguments

json

{
  "name": "search_businesses",
  "arguments": {
    "query": "guesthouse near the beach"
  }
}

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

Input JSON Schema

json

{
  "$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": {
      "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": {
      "description": "vertical: optional business type: hotel, restaurant or salon",
      "type": "string",
      "enum": [
        "hotel",
        "restaurant",
        "salon"
      ]
    },
    "date": {
      "description": "date: optional local date to check availability for, YYYY-MM-DD, e.g. \"2026-11-14\"",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "partySize": {
      "description": "partySize: optional number of people (restaurants) or guests (hotels), e.g. 2",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "limit": {
      "default": 10,
      "description": "limit: maximum results, 1–10",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "query"
  ]
}

Output schemaJSON Schema

Output JSON Schema

json

{
  "$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"
          },
          "sponsored": {
            "type": "boolean"
          }
        },
        "required": [
          "businessId",
          "name",
          "sponsored"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": {}
}

Behavior annotationsMCP

Tool annotations

json

{
  "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