add_filter
ChatGPTAdd a filter to the accumulated session state. Merges with existing — does not replace. type: "titles" | "companies" | "locations" | "schools" | "country" | "state" | "excluded_companies" | "excluded_titles" | "exclude_sources" | "exclude_profile_keys" | "exclude_search_query" | "years_experience_min" | "years_experience_max" | "company_size_min" | "company_size_max" | "specialization" | "has_clearance" | "open_to_remote" | "power_filters" For public-profile searches, use years_experience_min/max for seniority-style constraints rather than a seniority filter. value: ONE entity name per call. Call multiple times for multiple values. For ranges — integer string: add_filter("years_experience_min", "5") For current exclusions — entity name or CSV: add_filter("excluded_companies", "Microsoft, Google") For MCP-side result exclusions: add_filter("exclude_sources", "ats,internal") add_filter("exclude_profile_keys", "profile-key-1,profile-key-2") add_filter("exclude_search_query", "https://app.seekout.io/app?search_id=...") These are not Runtime entity filters and are stored under session["exclusions"]. For the typed clearance wrapper — truthy string: add_filter("has_clearance", "true") For remote availability — truthy string: add_filter("open_to_remote", "true") For generic power filters — filter id string from browse_power_filters: add_filter("power_filters", "general.authorizations.security_clearance") Typed power-filter wrapper (public vertical only) — one call, one runtime power filter: has_clearance — candidates who list a security clearance on their profile open_to_remote — candidates open to remote work Entity names are RESOLVED IMMEDIATELY against SeekOut's database. Check resolution feedback — if names didn't resolve, try alternative spellings. For titles: validates level and function against query_context. Server BLOCKS mismatches. Location hierarchy: US: add_filter("state", "California") for states, add_filter("locations", "Nashville") for cities. Non-US: FIRST set_index("Europe"), THEN add_filter("country", "Sweden"), optionally add_filter("locations", "Stockholm").
add_search_to_workspace
ChatGPTSave the current session's search as an additional Saved search on a workspace. Unlike `update_workspace_search (which replaces the workspace's single Base search), this tool POSTs a new Saved search alongside any existing Saved searches and the Base. Use this when the user wants to bookmark multiple distinct candidate populations under one workspace — for example, "senior PMs", "staff PMs", and "GitHub-active PMs" all under one "PM intake" workspace; or a public-profile search alongside a GitHub search. Vertical-aware: stores the active session's Runtime query in query-store, then saves the same route-shaped {pathname, search}` payload recruit-ui creates for manual workspace Saved searches. This lets the Saved search rehydrate into the correct vertical view when clicked. Out-of-scope verticals raise an error rather than silently saving a public-profile-shaped query. Returns the new search id and a link to open the workspace. Args: workspace_id: ID of the workspace to add the Saved search to. name: Human-readable name for this Saved search (shown in the "Saved searches" panel on the workspace). Required — pick a short label that describes the candidate population (e.g., "Senior PMs in NYC", "Rust devs with 100+ stars"). user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
add_to_workspace
ChatGPTAdd candidate profiles to a workspace. ALWAYS include user_intent (user's exact message) and user_intent_category. Resolves the workspace by name, validates profile keys, and adds profiles. Duplicates are handled gracefully (idempotent merge). Max 100 profiles per call. For bulk adds from the active search, pass from_current_search=True, skip=0, limit=100. To add the next page, call again with the returned batch.next_skip value. Args: workspace_name: Name of the workspace to add profiles to. profile_keys: Candidate profile keys from search results (max 100). from_current_search: When true and profile_keys is empty, add the current search page instead. skip: Current-search offset for paginated bulk adds. limit: Number of current-search candidates to add (max 100). user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
analyze_bench_depth
ChatGPTAnalyze bench depth for one or more critical roles. For each role: searches the Employee index by title AND by expanded skills (via skill_resolver), merges & dedupes by profile_key, scores skill-overlap percentage against the role's required skills, and returns the top candidates with how each was found. Args: critical_roles: role titles to analyze (e.g., "Principal ML Engineer"). Capped at `max_roles. scope_manager: optional "Name / email" string. Restricts the search to that manager's direct reports (existing manager` filter; profile-key-based subtree filtering isn't supported by runtime — see F1.5 close-out). department: optional department name to scope to. max_roles: cap on the number of roles processed. max_candidates_per_role: cap on top candidates returned per role. use_org_context: opt-in for skill_resolver org-context expansion. Default True for internal_talent.
browse_power_filters
ChatGPTBrowse available power filters for the current search vertical. Returns categories and their power filters. Use without arguments to see all categories. Pass a category name to see its filters. Apply filters using add_filter(type="power_filters", value="filter_id"). Custom power filters created by your organization are included. Use ONLY for these specific scenarios: - Security clearance searches (e.g., TS/SCI, Secret, Top Secret) - Government/defense sector searches - Career level filters for big tech companies (e.g., L5, L6, Principal) - When the user explicitly asks for a power filter or custom filter Do NOT use for general searches — standard filters (titles, companies, locations, skills) are better handled by add_filter.
check_contacts
ChatGPTCheck status of all background contact retrieval jobs. Auto-detects which jobs are running (emails, phones, or both). Returns results for completed jobs and status for in-progress ones. Call get_emails() or get_phones() first to start a retrieval job.
check_credits
ChatGPTCheck your remaining export and contact credits. Returns a summary of available and used credits for: - Export credits (used when exporting profiles to Excel or ATS) - Contact credits (used when retrieving email addresses) Args: user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
clear_search
ChatGPTClear filters, query, and reset index to NorthAmerica. Use to start a fresh search within the same session. MCP-only exclusions are intentionally preserved so recruiter-requested suppression rules keep applying across search refinements. Internal-talent guard: if the current search has critical HR filters whose values are visibly present in the original query_context, clear_search returns `blocked_critical_clear` instead of resetting. This prevents zero-result recovery from bypassing employee/org anchors.
compare_markets
ChatGPTCompare talent pools across multiple cities side by side. Runs parallel searches with the same query/filters but different location constraints for each city. Returns per-city pool sizes and facet breakdowns (companies, titles, seniority, skills). Args: cities: List of city names to compare (2-6 cities). Example: ["New York", "Seattle", "San Francisco"] query: Boolean search query with cur_title:() syntax. Example: cur_title:("Software Engineer") titles: Optional comma-separated title filter values. skills: Optional comma-separated skill filter values. seniority: Optional comma-separated seniority filter values. index: Geographic index (default NorthAmerica).
count_results
ChatGPTQuick count of candidates matching current session filters. No profiles returned. For public profiles: requires at least one filter or a boolean query (title, location, companies, skills boolean, etc. — any single constraint is enough). Returns {total_count, facets}. For non-public verticals: counts with whatever filters are active. Use to check pool size BEFORE calling search_people. include_facets: Whether to include facet breakdowns in the response (default True).
create_workspace
ChatGPTCreate a new workspace. Behavior depends on from_current_search: - from_current_search=False (default): create a new empty workspace. - from_current_search=True: create a new workspace seeded with your current search (query, filters, index). Always provide the user a link to the workspace. Vertical-aware: when the active session vertical is github, healthcare, nursing, or academic, the workspace's base search is built using that vertical's query shape so recruit-ui rehydrates into the correct vertical view. Out-of-scope verticals (internal_talent, ats, ar, etc.) raise an error rather than silently saving a public-profile-shaped query. Hire-intent EXPRESS pipeline: when from_current_search=True and user_intent_category="hire", the workspace is created with creationType="EXPRESS" so recruit-api asynchronously generates a draft questionnaire and evaluation rubric from the description. Provide a substantive description (at least the target role plus 2 must-haves) for hire-intent flows — this seeds the questionnaire generator. For non-hire intents (research, competitive_intel, market_sizing, outreach) the workspace is created with creationType="QUERY" — base search saved, no questionnaire generated. Returns the workspace id, name, and a link to open it in SeekOut. Args: name: Name for the new workspace. description: Hiring-manager intent / role headline. Strongly recommended for hire-intent workspaces (seeds the EXPRESS questionnaire generator). Capture target role, must-have skills, nice-to-haves, level, location preferences in 2-4 sentences. Long descriptions are truncated at sentence boundaries; thin (<50 char) descriptions on hire intent are logged but not blocked. from_current_search: When True, seed the workspace with the current search session (query, filters, index). user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other. When "hire" combined with from_current_search=True, the workspace uses EXPRESS creation type to populate questionnaire + rubric.
describe_org_schema
ChatGPTDescribe the Employee-index schema for a single org. Call ONCE at the start of an internal_talent session, then rely on the returned vocabularies + `configurable_data_fields to decide which filters and skill names are usable for this tenant. Returns JSON with: - available_filters: filter names + descriptions - skill_facets / department_vocab / title_vocab / seniority_vocab / office_location_vocab: per-tenant real vocabularies - configurable_data_fields: union of CD keys observed across the sample, with per-key occupancy in [0, 1] - tenant_shape: populated-rate signals for top-level fields (skills / department / manager / hierarchy / internal_skills) - total_employees, sample_size, as_of` Args: org_domain: Org domain (e.g., 'hooli.com'). Defaults to the authenticated org if omitted. force_refresh: Bypass the 1h cache. Use sparingly — the schema only changes when the org adds/removes configurable_data fields or changes index settings, which is rare.
discover_companies
ChatGPTFind companies in an industry using AI generation + SeekOut database verification. Uses an LLM to generate 50 companies in the industry, then verifies each against SeekOut's entity database. Returns only verified companies ready for add_filter. Use for industry/sector queries: "at biotech", "in cybersecurity", "gaming companies", "unicorn", "series b startups". Then add results: add_filter("companies", "Company1, Company2, ...") industry: Industry keyword (e.g. "biotech", "cybersecurity", "gaming", "fintech") location: Optional geographic hint (e.g. "Texas", "UK")
execute_app_action
ChatGPTExecute a UI-triggered app action through the audited action executor.
export_profiles
ChatGPTExport candidate profiles to Excel or Google Sheets. ALWAYS include user_intent (user's exact message) and user_intent_category. Returns a download URL for the exported file. Supported formats: 'excel', 'sheets' (both produce an Excel file). For batches over 25 profiles, returns a confirmation prompt with credit impact details. Call again with confirm_large_batch=True after user confirms. Args: profile_keys: List of candidate profile keys to export. format: Export format — 'excel' or 'sheets' (both use Excel format). project_name: Optional name for the export project. confirm_large_batch: Set to True to confirm a batch over 25 profiles. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
export_to_ats
ChatGPTExport candidate profiles to your ATS (Applicant Tracking System). ALWAYS include user_intent (user's exact message) and user_intent_category. The ATS connection is auto-detected from your account. If you have multiple export-capable ATS connections, specify which one to use or call list_ats_connections first. Args: profile_keys: List of candidate profile keys to export. ats_connection_id: Optional ATS connection ID. Auto-resolved if omitted. project_name: Optional name for the export project. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
get_emails
ChatGPTStart email retrieval for candidate profiles. ALWAYS include user_intent (user's exact message) and user_intent_category. Kicks off a background job to retrieve ranked email addresses. Use check_contacts() to get results when ready. Results may be returned immediately if contacts are already cached. For batches over 25 profiles, returns a confirmation prompt with credit impact details. Call again with confirm_large_batch=True after user confirms. Args: profile_keys: List of candidate profile keys from search results. confirm_large_batch: Set to True to confirm a batch over 25 profiles. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
get_phones
ChatGPTStart phone number retrieval for candidate profiles. ALWAYS include user_intent (user's exact message) and user_intent_category. Kicks off a background job to retrieve phone numbers. Use check_contacts() to get results when ready. Results may be returned immediately if contacts are already cached. For batches over 25 profiles, returns a confirmation prompt with credit impact details. Call again with confirm_large_batch=True after user confirms. Args: profile_keys: List of candidate profile keys from search results. confirm_large_batch: Set to True to confirm a batch over 25 profiles. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
get_profile
ChatGPTFetch full candidate profiles by profile key(s) from search_people results. keys: CSV string of profile_key values (max 15). Returns unified profiles with data from all available verticals — public LinkedIn profile, ATS applications, internal talent data — merged into one response. Keys from different verticals (e.g., a GitHub key + a public profile key) are automatically de-duplicated — the same person appears once with data from all verticals.
get_search_links
ChatGPTRetrieve SeekOut search links from past searches in this session. Each search (search_people, count_results, unified_search, market_analysis) generates a link that opens the search in the SeekOut UI for verification. Args: vertical: Filter by vertical (e.g. "public", "github", "academic", "ats"). search_id: Filter by a specific search ID. tool: Filter by originating tool ("search_people", "count_results", "unified_search", "market_analysis"). Returns all matching links from the session, most recent first.
get_state
ChatGPTReturn accumulated filters, query, index, and (optionally) the runtime query. Default mode returns the session state as JSON: filters, the boolean query text, the active geographic index, the active vertical, and any ATS-specific context. Use this to inspect the session before searching or to debug filter accumulation. When `include_runtime_query=True (or store=True), the response also includes runtime_query — the exact dict that would be POSTed to the active vertical's Runtime API endpoint — plus endpoint. Use that for bulk operations like SearchPeopleKeys that bypass the MCP's result cap. When store=True, also persists the query via the query store and returns a shareable SeekOut app link in the link field. Args: include_runtime_query: When True, include the runtime API payload under runtime_query and the target endpoint under endpoint. top: Maximum results in the runtime query (Runtime accepts higher than the MCP's 25 cap). Only meaningful with include_runtime_query or store. skip: Pagination offset for the runtime query. include_facets: Whether to include facet requests in the runtime query. store: When True, store the runtime query and return a shareable SeekOut app link (implies include_runtime_query`). user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
list_ats_connections
ChatGPTList available ATS connections for your organization. Returns the ATS integrations configured for your account, including connection ID, name, ATS type, and supported features. Use the connection ID with export_to_ats to export candidates to a specific ATS. Args: feature_filter: Optional feature to filter by. Valid values: 'export', 'inbound', 'analytics', 'connect', 'rediscovery'. When set, only connections with that feature are returned. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
list_resources
ChatGPTList all available resources and resource templates. Returns JSON with resource metadata. Static resources have a 'uri' field, while templates have a 'uri_template' field with placeholders like {name}.
list_search_contexts
ChatGPTList this caller's recent searches for explicit-handle recovery. This tool never selects a context. Compare the bounded summaries with the user's current request, then retry the interrupted operation with the exact `search_context_id you chose. If none matches, start an independent search with set_query(new_search=true)`. Args: limit: Number of recent contexts to return, from 1 through 10. organization: Optional home or delegated organization ID/domain. The server verifies the current credential grants this scope and never mixes contexts from another organization.
list_workspaces
ChatGPTList your workspaces. Optionally filter by name. Returns workspace id, name, profile count, creation date, and a link to open each workspace in SeekOut. Use this to find a workspace before adding profiles to it.
market_analysis
ChatGPTAnalyze the talent market for your current search criteria. Uses current session state (query, filters, index, vertical) to compute pool sizes and facet distributions scoped to your current search context. Args: expand_regions: If True and searching public profiles, also show pool sizes for all 6 geographic regions. Default False — only analyzes the current index/vertical. include_region_facets: If True (requires expand_regions), include per-region facet distributions (companies, titles, skills by region). Can be verbose — use only when comparing regions. Returns: JSON with pool_size, distributions, and optionally by_region + distributions_by_region.
pipeline_overview
ChatGPTSample-derived ATS pipeline analytics in one call. Use when the user asks "give me a pipeline overview", "where are candidates by stage?", "who's running the most reqs?", or anything that wants a one-shot summary of the active pipeline state. Saves 14-18 LLM turns vs composing per-status / per-recruiter count_results calls. Args: connection_id: Optional ATS connection ID. Defaults to the session's resolved connection (set when the user first searched ATS). req_filter: Optional job_id or requisition_id to scope to one req. Empty = all reqs in the connection's pipeline. time_range: Optional ISO-date range like "2024-01-01..2024-12-31". Empty = all time. (Currently informational — backend application filter does not yet expose applied_at range here.) breakdowns: Subset of {"status", "stage", "recruiter", "rejection_reason", "timeline"}. None or empty = all of them. Returns: { "connection_id": str, "ats_type": str, "sample_size": int, "status_breakdown": {...}, "pipeline_stages": {...}, "recruiters": {...}, "rejection_reasons": {...}, "application_timeline": {...}, "data_completeness_warning": {"notes": [...], "cache_hit": bool} } Notes: - source breakdown is intentionally out of scope for v1 — the field isn't in the response. - True time-in-stage transitions are not available; only current-stage breakdown is computed.
read_resource
ChatGPTRead a resource by its URI. For static resources, provide the exact URI. For templated resources, provide the URI with template parameters filled in. Returns the resource content as a string. Binary content is base64-encoded.
remove_filter
ChatGPTRemove a filter value, or clear all values for a field. To remove a specific value: remove_filter("companies", "Google") To clear entire field: remove_filter("companies") If the user's most recent message doesn't look like a drop instruction (e.g. "focus on must-haves" is a priority hint, not a drop), the server attaches an `advisory field to the response. The removal still proceeds — the advisory is informational only. Critical-filter anchor (non-public verticals only): each vertical declares a set of filter keys whose silent removal during recovery is the dominant constraint_relaxation failure. When type is in the active vertical's critical set, the server returns a status=blocked_critical_filter envelope unless the user clearly asked to drop it or the caller passes confirm=True. For internal_talent only, confirm=True` is ignored when the active value is visible in the original query_context; that closes the single-turn recovery bypass that drops employee/org anchors. WARNING: Removing 'companies' is almost always wrong. If the query specifies an industry or sector, keep that filter and broaden titles instead. Returning candidates at the WRONG industry is a critical precision error.
rename_workspace
ChatGPTRename one workspace by exact ID or one unique exact name. The ID route is tried first. A name is accepted only when exactly one case-insensitive exact match can be proved within a bounded paged scan; duplicate, partial, missing, or incompletely scanned matches perform no write and ask for the workspace ID. The new name is used exactly as supplied and cannot be blank, longer than 512 characters, or surrounded by whitespace. A destination name already used by another workspace is allowed. An identical current name is a no-op and performs no provider update. A changed result reports the old observed name and requested new name. Provider acknowledgement is not a persisted read-back or confirmation from downstream systems. Args: workspace_id_or_name: Exact workspace ID, or one unique exact case-insensitive workspace name. new_name: Exact requested new name, without surrounding whitespace.
report_bug
ChatGPTSend a bug report, feedback, friction report, or feature request to the SeekOut team. Use this when the user asks to report, log, or flag a problem with SeekOut — for example mismatched result counts, filters that were dropped, links that open the wrong results, or missing functionality. Share only details needed to diagnose the issue or describe the request. The report sends the supplied description, expected behavior, and reproduction steps to the SeekOut team through its support telemetry. When the request is isolated to one conversation, the server also attaches a bounded search snapshot: current query and query context, filter summary, index, vertical, and the last search link. It does not attach the conversation transcript or the full search history. Reports without an isolated search context omit the snapshot. Show the report id and summarize what was shared after the report is filed. Also use it to report friction: work that succeeded but cost more turns than it should have, because a search tool refused a value, applied a filter that then matched nothing, or needed several attempts before it worked. Send that as report_type friction once the work is done and before answering, as a single call covering the whole turn rather than one per obstruction. The server attaches its bounded record of tool obstructions from this search context, so a concise description of the task and its difficulty is sufficient. When suggested_next_action is report_bug, the server is suggesting this follow-up. Respect any client confirmation before sending. Search results that are merely not what was wanted are not friction — when the tools are working and the targeting is wrong, refine the search with the search tools instead of sending a report. Args: description: A concise account of the issue or request, including relevant observed behavior and the expected outcome. Preserve supplied evidence such as mismatched counts; never invent details. Exclude unrelated conversation or personal context. expected_behavior: What was expected to happen instead. report_type: One of: bug, feedback, feature_request, friction. Use friction when nothing is broken but the work was harder than it should have been. steps_to_reproduce: Only actions that were actually performed and are relevant to reproducing this issue. Omit if none are known; do not reproduce a search unless the user requested it. user_intent: Optional brief summary of the reporting task. Omit when description already supplies that context. Do not copy the full user message, conversation transcript, or unrelated details. user_intent_category: Optional task category: hire, research, competitive_intel, market_sizing, outreach, other.
resolve_skills_for_org
ChatGPTMap free-text skill terms onto the active org's real skill vocabulary. Use BEFORE `add_filter("skills", ...) (or add_filter("internal_skills", ...)) on internal_talent sessions to confirm that the term matches what the org actually has indexed. Returns three buckets: - mapped: direct matches in the org vocabulary. - synonyms: close alternatives — the LLM can decide whether to expand or pick. - unmatched: terms with no reasonable match — surface to the recruiter rather than silently filtering for nothing. Args: target_skills: free-text skill terms to map. org_domain: org_domain override (defaults to the authenticated org via describe_org_schema`). use_org_context: when False, returns the input unchanged with no LLM call. Default True for internal_talent.
search_entities
ChatGPTLook up an entity by name. Returns matching options with names and counts. ALWAYS call this BEFORE add_filter to validate entity names exist. Dispatches to the correct autosuggest endpoint based on the active vertical. type: Filter type name to look up. Use the same name as for add_filter: - Public profiles: "company" | "title" | "skill" | "location" | "school" | "major" | "degree" | "certification" - Other verticals: use filter names from available_filters (e.g., "conferences", "specialties", "topics", "nurse_type") query: Partial name to search (e.g., "neur" for NeurIPS, "card" for Cardiology) max_results: Number of suggestions to return (default 5) Returns: {suggestions: [{name, count}, ...]}
search_entities_batch
ChatGPTLook up multiple entities at once. Much faster than calling search_entities repeatedly. Use when you need to look up many values for a filter type at once. Dispatches to the correct autosuggest endpoint based on the active vertical. type: Filter type name (same as for add_filter / search_entities) queries: List of entity names to look up max_results: Suggestions per query (default 3) Returns: {resolved: [{query, name, count}], unresolved: [...], total_resolved, total_unresolved} Example: search_entities_batch(type="conferences", queries=["NeurIPS", "ICML", "AAAI"])
search_people
ChatGPTExecute a search using ALL accumulated session filters. Requires at least one filter or a boolean query in the session; a title specifically is no longer required — a skills boolean, a company or location filter, or any other constraint is accepted. Entity names are resolved at query time. Returns candidates with match_signals. Returns: {total_count, returned, candidates: [...], facets: {...}} Each candidate includes recruiter-useful match_signals such as function_mismatch, location_match, and skill_match when available. Review match_signals — exclude candidates with function_mismatch or location_match=false. skill_match shows which query skill terms (e.g. "MongoDB") appear in the candidate's full skills list. If skill_match=false, the candidate lacks the required skill — no need to fetch their full profile. If 0 results with location filters: reports global_count_without_location to guide relaxation. Broaden TITLE variants within the same function first. Relax location as a last resort.
set_index
ChatGPTSet the geographic index for searches. Default is NorthAmerica. Available indexes: NorthAmerica, Europe, Asia, Africa, Oceania, SouthAmerica, all Index mapping: NorthAmerica: US, Canada, Mexico Europe: UK, Germany, France, Sweden, Netherlands, Denmark, Spain, Ireland, Italy, Finland, ... Asia: India, China, Japan, Singapore, UAE, Saudi Arabia, Israel, Philippines, ... SouthAmerica: Brazil, Argentina, Colombia, Chile, ... Oceania: Australia, New Zealand Africa: South Africa, Nigeria, Kenya, ... all: fan out across all geographic indexes
set_query
ChatGPTSet or replace the boolean search expression. Typically contains `cur_title:() for role matching, but that is not required — skills-only, seniority-only, or company-name-only booleans are accepted. ALWAYS include user_intent (user's exact message) and user_intent_category`. boolean_query: The boolean search string. Recommended pattern: cur_title:("Policy Manager") for the role plus free-text skill keywords: cur_title:("Engineer") AND ("Python" OR "React"). Always quote multi-word titles. NEVER use skills:() syntax — it misses up to 49% of candidates. Use AND between must-have skill families and OR only inside a family for synonyms or acceptable alternatives. Do not use true:y or caret boosts for preferred terms. query_context: Original query text (e.g. "etl statisticians in LA"). Keep this stable across iterative refinements when possible. Used by add_filter("titles", ...) to detect function mismatches and keyword drops. If you start a genuinely new search in the same session, send the new query_context and stale filters will be cleared automatically. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
set_vertical
ChatGPTSwitch search to a different index vertical. Available verticals: public, github, academic, healthcare, nursing, ats, internal_talent Default is 'public' (standard talent search). Only switch when the user explicitly asks to search a specific index. For ATS with multiple connections: pass connection_id to select one, or omit to see available connections. Switching verticals resets filters (different verticals have different filter types). The response includes available_filters for the new vertical.
talent_dashboard
ChatGPTBuild a full talent-market report from verified searches in ONE call. May persist query variants in SeekOut to create reusable search links for the report. First build each query variant with the normal search tools and run verify_search on it (stop there — do not call search_people), keeping the query_id from each verify_search response. Every variant runs at the HIRING location and differs by sourcing strategy (tight vs broad, pedigree vs skills, adjacent titles, domain gate) — not by market. Compare other markets through context_metros; never widen or drop the hiring-location filter or build per-city queries for it. Then call this tool once with the labeled id list: it executes every count and the primary query's facet distributions server-side in a single batch and returns the assembled report. Queries that fail or expired are marked unavailable — their numbers are never guessed. Args: queries: Labeled verified searches, in priority order. Each item: {"label": "Q1", "query_id": "<from verify_search>", "metro": "Seattle Area" (for per-metro queries), "description": "what this query measures" (short, shown in the report's ledger — recommended for non-conventional labels)}. The FIRST item is the primary (tight) pool — its facets power the MAP and the employer/seniority/skills sections. Conventional labels (Q1 tight, Q1B national, Q2 broad, Q3 domain, Q4:<metro>, Q5B tier, Q8 analog, Q9 movement) unlock derived metrics and default descriptions. role_title: The role as posted, e.g. "Principal Product Designer". hiring_locations: REQUIRED. Metro names that are hiring locations. These are HIGHLIGHTED on the map; they do not populate it — the map is built from the primary query's location facet, so every market the search found appears without being named. Pass [] only for fully remote or nationwide roles. company: Hiring company display name. context_metros: Comparison-only metro names. These are MEASURED for EVERY strategy: each location-scoped query (Q1, Q2, Q3, Q8, Q9, custom) is re-run once with its location filter widened to every declared market, so each market gets a real count from that strategy's own boolean — including a real zero, which is a finding. Q1's run also sizes the map. Q1B (no location filter) and Q4:<metro> rows are not widened. A market the index cannot hold is reported in `unplotted_markets rather than plotted. This is how markets are compared — name them here instead of building a query per city. analytical_hook: 1-2 sentences on why the role is hard to source. Returns: JSON report — {report_id, queries: [{label, total_count | unavailable}], facets, metro_map, map_scale, unplotted_markets, derived (Calc-marked), citation}. map_scale is the single granularity every map point shares ("city", "state" or "country"), taken from the location facet — quote counts as that scale, because "1,200 in Texas" and "1,200 in Austin" are different claims. unplotted_markets lists markets the map could not draw and why; report those as gaps, never as markets with nobody in them. A map point whose count_source is "declared" carries no count at all — no query in this report measured it, so describe it as unmeasured, never as empty. A point's nearby names the suburb markets folded into it; those counts are NOT included in its count (the facet's buckets overlap), so describe it as "<market> and nearby", never as a sum. Per-strategy market counts are in query_maps[<query_id>].market_counts ({market, count, plotted_as, reason} at market_scale): quote each with BOTH its strategy label and its market; count: null is unmeasured (the reason says why — including this report's cap of widened strategies), never zero. An index_mismatch_note` means the primary query ran against an index that does not hold the hiring market: every count structurally undercounts, so fix the index and re-verify before reporting them.
unified_search
ChatGPTSearch across all available verticals and geographic indexes in one call. Uses current session state (query + filters) to search across public profiles (all geographic indexes), GitHub, Academic, Healthcare, Nursing, ATS, and Internal Talent — returning deduplicated, merged candidate profiles. For ordinary public-profile Search Results rendering, prefer search_people after verify_search approves because it opens the native Search Results app. unified_search is still an acceptable fallback/substitute when search_people is not available in the current tool surface, or when the user explicitly asks for cross-vertical/landscape results. Keep any fallback mechanics out of recruiter-facing prose. Args: max_results: Maximum candidates to return (1-50, default 25). verticals: None to auto-detect relevant verticals from query, or comma-separated string "public,github,academic" or list ["public", "github", "academic"]. exclude_verticals: Verticals to exclude — comma-separated string or list. include_facets: Include facet distributions per vertical in response. detail: "compact" (default) for lightweight summaries with vertical badges, "full" for rich profiles with work history, education, all skills. Returns: JSON with candidates from across verticals, each tagged with source_verticals, plus per_vertical_counts, searched/skipped verticals, and dedup_stats.
update_workspace_search
ChatGPTUpdate an existing workspace's base search from the current session. Replaces the workspace's base search with the current query, filters, and index from your session. A search must be active before calling this tool. Vertical-aware: when the active session vertical is github, healthcare, nursing, or academic, the workspace's base search is rebuilt using that vertical's query shape so recruit-ui rehydrates into the correct vertical view. Out-of-scope verticals raise an error. Note: this tool replaces the base search only. It does NOT regenerate the workspace's questionnaire or evaluation rubric — those are produced by the EXPRESS pipeline at workspace-creation time. To get a new questionnaire from a refreshed description, create a new workspace with `create_workspace(from_current_search=True, user_intent_category="hire")`. To create a new workspace instead, use create_workspace. Returns the workspace id and a link to open it in SeekOut. Args: workspace_id: ID of the workspace to update. user_intent: The user's latest raw unedited message. ALWAYS pass the user's original request exactly as they stated it. user_intent_category: One of: hire, research, competitive_intel, market_sizing, outreach, other.
verify_search
ChatGPTVerify current search quality before rendering candidate results. Use after set_query/add_filter and before search_people. This is the pre-render gate for recruiter candidate searches: it runs Runtime count/facet evidence plus a bounded non-rendered candidate sample and returns a decision: - show: the search is representative enough; call search_people next. - refine: edit query/filters and call verify_search again. - ask: ask one clarification before rendering candidates. - no_results: preserved constraints produce no usable pool. - blocked: unsupported or compliance-blocked search. criteria: Optional extra must-have criteria for judging sample fit. sample_size: Number of non-rendered candidates to sample, capped at 15. include_facets: Include Runtime facet evidence in the decision.
