Pearl

Use this when the user wants to match up to 20 place names or structured Calendar/email venue signals against Pearl’s canonical venue catalog. IDs must agree with supplied names, types, geography, and address evidence; contradictions require review. NYC boroughs use canonical coordinates, never whole-city aliases. Returns review results without writing data. Never discard conflicting evidence or promote a review result to exact without resolving it with the member.

places_match

Use this when the authenticated member wants current table availability for one canonical Pearl venue, local date, and party size. Reuses Pearl’s exact-cell refresh lifecycle and can continue a pending Pearl refresh ID; it never books, holds, changes, or cancels a reservation, and an unknown result is not sold out. When checked_live is false, say when the times were last checked (observed_at) instead of calling them current. Hand the member booking_url or pearl_url to book, and follow next_step.

reservations_availability

Use this only after the member reviewed the import preview and explicitly confirmed which items they actually attended. Commits the preview bound to a valid action handle; unconfirmed attendance, suggested matches, and same-day duplicates stay skipped unless individually confirmed.

visits_import_commit

Use this only after the member reviewed the before/after visit preview and explicitly confirmed it. Changes can include publishing a visit comment or changing its audience according to the confirmed comment_visibility; edits to already shared comments can be visible to that audience. Use a new idempotency_key that is different from the prepare call. The update is rejected if the visit changed after preview; a same-venue, same-local-day collision requires separate confirmation.

visits_update_commit

Use this when the member asks what is new, newly opened, just opened, or coming soon in an area. Returns recency-ranked coming-soon and newly-opened Pearl venues; when there are no qualifying openings, it explicitly marks the result insufficient and returns established top venues only as alternatives.

venues_new_openings

Use this only for an open-ended personalized request with no hard cuisine, dish, neighborhood, mood, occasion, or named-place criterion, optionally narrowed by city or venue type. Without a type it recommends restaurants; set type for bars, wineries, hotels or other venues. For concrete criteria use venues_search instead; when the user also asks for explicit profile-fit reasoning, call profile_get concurrently. The response is bounded to three candidates by default (five maximum), identifies one evidence-supported top pick, labels whether member taste was actually applied, and includes availability, hours, and allergy caveats. For more options, call again with exclude_ids set to the ids already shown. Each venue carries pearl_url and, when known, booking_url; call reservations_availability only for venues whose availability_supported is true.

venues_recommend

Use this when the authenticated member wants to review accepted friends plus incoming and outgoing pending requests. Returns three lists (friends with friends_since; incoming_requests and outgoing_requests with requested_at), each row carrying friendship_id, user_id, username and display name, up to 100 rows per list; only members the caller may currently view are included. Read-only: it never accepts, declines, cancels or sends a request.

friends_list

Use this when the authenticated member wants to review linked or imported Pearl reservations. Follow next_cursor until pagination.coverage_state is complete; total_count is exact for the member-scoped unified reservation source. Each reservation carries local_time_label and timezone (the venue's zone): say the time from those, never from the UTC reservation_at. Returns user-facing details and a pearl_url to the member's reservations in Pearl, never booking credentials or provider deep links.

reservations_list

Use this when the authenticated member wants to list their Pearl trips and custom collections with exact stop counts. Follow next_cursor until pagination.coverage_state is complete; total_count is exact for the active member-owned collection index.

trips_list

Use this when the authenticated member wants to review committed Pearl visits or asks about favorite, best-rated, cuisine-specific, city-specific, or trip-related places they have visited. Use sort=score for favorites. For complete recent history or a historical extraction window, follow the HMAC-protected next_cursor until pagination.coverage_state is complete or the oldest returned visit is earlier than the window start; reuse the same city and min_score plus note and sort filters. Filtered favorite/trip/category discovery is explicitly labeled partial when no authoritative total is available. Full notes remain opt-in. Deleted or merged venues are excluded, and the tool never accepts a member ID.

visits_list