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.

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. 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. 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.

venues_recommend

Use this when the authenticated member wants to review accepted friends plus incoming and outgoing pending requests.

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. Returns user-facing details, never booking credentials or 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