Happenstance

Find more results for an existing Happenstance search. Use this instead of starting a new search when you want additional results — it guarantees different people by excluding everyone already returned. Only call this when has_more was true in a previous get-search-results response. Costs 2 credits. Returns a page ID to use with get-search-results. After calling this, use get-search-results with the original searchId plus the returned pageId to poll for and retrieve the new results. Documentation: https://developer.happenstance.ai

find-more-results

Gets the user's credit balance, purchase history, usage history, and auto-reload settings. Call this proactively before running searches or research to make sure the user has enough credits. Also call this after completing searches or research so the user can see their updated balance. If the balance is low, let the user know and suggest using create-credits-checkout-session to purchase more. Documentation: https://developer.happenstance.ai

get-credits

Gets details of a specific Happenstance group including its full member list. Returns the group name, image, slug, member count, and each member's name and profile image. Use get-groups first to discover available group IDs, then use this tool to see who is in a specific group. This is especially useful for at-mentions in searches. You can @mention a group member's name in a search query to filter results to that person's connections (e.g. "engineers @Jane Smith knows"). Use this tool to look up the exact name to at-mention. Documentation: https://developer.happenstance.ai

get-group

Gets the Happenstance groups the user is a member of. Returns a list of group IDs and names. Use get-group with a specific group ID to see its members. Knowing group members enables at-mentions in searches — @mentioning a person's name in a search query filters results to that person's connections. Documentation: https://developer.happenstance.ai

get-groups

Get the status and results of a Happenstance person research. Call this after research-person to check if the profile is ready. If status is "running", wait a bit and call again. If status is "completed", the full profile is included in the response. Documentation: https://developer.happenstance.ai

get-research-results

Get the status and results of a Happenstance network search. Call this after search-network to check if results are ready. If status is "running", wait a bit and call again. If status is "completed", the results are included in the response. IMPORTANT — Understanding the mutuals structure: The response uses a normalized format. There is a top-level "mutuals" array containing all unique mutual connections across all results. Each person in the "results" array has a "mutuals" field with references (by index) into that top-level array, along with an affinity_score. When presenting results, resolve ALL mutual references for each person — not just the first one. Each person may have multiple mutuals who can make an introduction. IMPORTANT: If has_more is true in the response and you want more results, use the find-more-results tool instead of starting a new search. It guarantees different results by excluding all previously returned people. Note: find-more-results costs 2 credits (same as a new search). After calling find-more-results, call this tool again with the original searchId plus the returned pageId to poll for and retrieve the new results. Documentation: https://developer.happenstance.ai

get-search-results

Gets the current user's Happenstance profile information. Returns email, name, profile image URL, and a list of the user's friends (names). Use this to identify who the current user is or to personalize responses with their name. Documentation: https://developer.happenstance.ai

get-user

Creates a Stripe checkout session to purchase Happenstance credits. Returns a checkout URL that the user can open in their browser to complete the purchase. Available packages: 100 credits ($25 - $0.25/credit), 1000 credits ($200 - $0.20/credit), 10000 credits ($1500 - $0.15/credit). After purchase, credits are automatically added to the user's account via webhook — no manual step needed. Use get-credits first to check the user's current balance before suggesting a purchase. You can also check to see if the user has auto-reload enabled. If the user is unsure how many credits to buy, recommend 100 credits to start. IMPORTANT: Always return the full checkout URL to the user exactly as provided — do not truncate or shorten it. Documentation: https://developer.happenstance.ai

create-credits-checkout-session

Research a specific person to get detailed professional profile information. This tool starts the research and returns immediately with a research ID. The research runs asynchronously and can take 30+ seconds to complete. Use the get-research-results tool with the returned research ID to check status and retrieve the profile. Costs 1 credit per request. Documentation: https://developer.happenstance.ai

research-person

Happenstance is a People Search Engine that takes natural language queries and returns a list of people that match the query. This tool starts a search across the user's network. It returns immediately with a search ID. The search runs asynchronously and can take a few minutes to complete. Use the get-search-results tool with the returned search ID to check status and retrieve results. If the user asks explicitly for people they know, set includeGroups to false, includeFriends to false, and includeConnections to true. You can use @mentions in the search query to filter results to a specific person's connections (e.g. "engineers @Jane Smith knows"). You can at-mention your friends or other members of a group that you are in. Use get-groups and get-group to look up member names for at-mentions, use get-user to look up your friends for at-mentions. Documentation: https://developer.happenstance.ai

search-network