SeekOut

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

Find 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 a UI-triggered app action through the audited action executor.

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

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

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

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

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

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

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

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

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

Look 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}, ...]}

Look 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"])

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

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

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