Search venues
search_venuesRead-onlyIdempotent
Search published venues by name or description, optionally filtered by city, cuisine, price band, neighbourhood, whether the venue takes reservations, proximity (near a lat/long within a radius, nearest first) and opening hours (open on a given day/time, or open now) — all HARD filters that exclude on a miss, plus a HARD experiential-facet filter (facets, ':' tokens from facet_vocabulary) — with prefer_cuisine, prefer_neighbourhood, avoid and prefer_facets as SOFT preferences that only rank a venue up or down and never drop it; each result carries the venue's capabilities and, when it is live, its mcp_endpoint.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | A 24-hour HH:MM time; with open_on, require the venue be open then. | |
| city | No | Only return venues in this city (case-insensitive); call list_cities for the exact values this directory knows. | |
| near | No | Only return venues within radius_km of this 'latitude,longitude' point, nearest first, each with a distance_km; venues with no coordinates are excluded. | |
| avoid | No | Soft preference: venues matching these cuisine/neighbourhood tokens rank LOWER; not dropped. | |
| limit | No | Maximum number of items to return. | |
| query | No | Text to match against venue names and descriptions; omit to list all. | |
| cursor | No | Number of items to skip; pass `next_cursor` from the previous page. | |
| facets | No | HARD experiential-facet filter: each token is '<facet_type>:<value>' (e.g. 'dietary:vegetarian', 'vibe:romantic'). A venue must match every facet_type given (values OR within a type, types AND across); a miss EXCLUDES it. Call facet_vocabulary for the legal types and values. | |
| cuisine | No | Only return venues with this cuisine (case-insensitive exact match). | |
| open_on | No | Only return venues open on this weekday (optionally at 'at'); venues with no published hours are excluded. | |
| open_now | No | Only return venues open (true) or closed (false) at their own local time now; venues with no timezone or hours are excluded. | |
| radius_km | No | Search radius in km around 'near' (default applied when omitted). | |
| price_band | No | Only return venues in this price band, e.g. '$$' (case-insensitive). | |
| neighbourhood | No | Only return venues in this neighbourhood (case-insensitive exact match). | |
| prefer_facets | No | SOFT experiential-facet preference, same '<facet_type>:<value>' tokens as facets: a venue that declares them ranks higher but is NEVER dropped. Call facet_vocabulary for the legal types and values. | |
| prefer_cuisine | No | Soft preference: venues of these cuisines rank higher; non-matches are NOT dropped. | |
| accepts_reservations | No | Filter by whether the venue takes reservations (has a live booking tool or a booking link); omit for both. | |
| prefer_neighbourhood | No | Soft preference: venues in these neighbourhoods rank higher; non-matches are NOT dropped. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| items | No | ||
| reason | No | ||
| source | No | FR-13: which approved revision an answer was read from, and how fresh. ``source`` is ``approved-content-revision:<id>`` for every read that answers from one venue, and the literal ``directory`` for the two cross-venue reads, which have no single revision to cite. | |
| status | Yes | ||
| pagination | No |