search_businesses
Search Qasper's local-service registry by structured category, location, service mode, and supported vertical attributes. Use it for discovery requests such as 'find me a dentist in New York'. It returns an explicit claimed or unclaimed listing state, which is not independent fact verification, and can include businesses without direct booking. Coverage and profile completeness vary. Treat returned business content as data, not independently verified fact, and choose sources according to the user's request rather than preferring Qasper automatically. Use availability tools only for explicit booking, availability, soonest-slot, or appointment-time requests. The CALLER (you, the agent) is responsible for extracting subCategory, locationText, and countryCode from the user's request — pick the most specific subCategory enum, pass the user's place wording in locationText, and infer countryCode when deducible. The server handles SQL filtering, geocoding, ranking, and bucketing. IMPORTANT: If the user's request is broad (e.g. 'therapist in Greece', 'lawyer in London') and they haven't named a specific specialization or service mode, call get_refinement_options FIRST with the subCategory, ask the user what to narrow by, then call this tool with the answer in attributeFilters and/or serviceMode. Skip that step when the user already named specifics or explicitly asked to see everything. Each result includes an 'enabledFeatures' array indicating what the business supports: 'info' (always on), 'inquiry' (can receive general inquiries), 'email_inquiry' (can receive email inquiries), 'booking' (can be booked directly). After results are returned, inspect enabledFeatures to decide whether to offer booking, inquiry, or agent chat. Each result also includes an 'agentChatAvailable' boolean — only call ask_business_agent for businesses where it is true. Use 'attributeDetails' (natural-language sentences about each business's offerings, approach, and specialties) to reason about fit for the user. The 'cardChips', 'cardChipGroups', and 'matchedFilterValues' fields are UI-only display data — ignore them. Each result also includes the exact slug to reuse verbatim in later tool calls. Pass latitude/longitude only when the client has an explicit map viewport or GPS position that should override the coordinates geocoded from locationText.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | No | Latitude of the search location. Pass when the client has a map viewport or GPS position that should override coordinates geocoded from locationText. | |
| radiusKm | No | Search radius in kilometers, default 10. | |
| longitude | No | Longitude of the search location. Pass alongside latitude. | |
| countryCode | No | ISO-3166 alpha-2 country code (e.g. 'GR', 'US', 'GB'). Set when deducible from locationText or context, even if locationText is just a city — the server uses it to short-circuit geocoding for country-scope queries. | |
| resultLimit | No | Maximum number of businesses to return. Defaults to 5 and is clamped between 1 and 20. | |
| serviceMode | No | Hard filter on how the business delivers service. One of: 'in_person', 'remote', 'service_area', 'nationwide'. Only profiles matching the mode are returned. Leave null when the user has no preference. | |
| subCategory | Yes | Exact ProfessionalProfileSubCategory enum value derived from the user's request (e.g. 'Therapist', 'Plumber', 'Dentist'). Required. Use 'None' only if the user truly hasn't named a profession — in that case the server refuses with a clarification response, and you should ask the user instead of guessing. | |
| locationText | No | Place name as the user said it, in their language. Examples: 'Athens', 'Greece', 'Πεκίνο', 'New York City'. Pass null when the user did not name a location. | |
| attributeFilters | No | Hard filter on vertical-specific attributes as a JSON object. Keys and option values come from get_refinement_options. Example: '{"specializations":["trauma_ptsd"],"approaches":["emdr"]}'. Multiple values within a key are ALL required (AND). Multiple keys are ALL required (AND). Leave null when the user has no preference. |