await_mcp_search_update
ChatGPTWait for a change to this search, bounded by max_wait_seconds. Returns approved counts, partial status, done and a cursor. Stop when done=true. This wait does not start another search.
Overview
Vettara lets authorized workspace users prepare executive-search briefs, create editable MCP search sessions, launch private candidate searches, monitor run status, review compact candidate results, and export completed project CSVs from ChatGPT. Access is enforced through Vettara OAuth and each user only sees records available to their Vettara workspace permissions. Vettara supports sourcing and research workflows only and does not make hiring decisions.
Tools
create_mcp_search_session
ChatGPTUse this only when the user explicitly asks GPT to prepare an editable Vettara brief before launch. Do not use it as the default path for candidate requests, and never open or continue Vettara AI chat.
edit_mcp_search_session
ChatGPTUse this when the user asks to change, narrow, broaden, or refine a Vettara MCP session before launch. If the source session is already linked to a project, duplicate_if_locked=true creates a new editable MCP session and applies the edits there.
export_vettara_project_csv
ChatGPTUse this when the user wants a CSV/spreadsheet/download link for a Vettara project, launch, job, MCP session, or project name. This is the full-results export path; prefer it over fetch when more than a preview is needed. Leave include_csv_text=false so ChatGPT receives a link instead of a large CSV payload.
fetch
ChatGPTUse this when the user needs details for a known Vettara project, MCP session, launch, job, candidates, run, or CSV URI/id. Supports vettara://session/{id}, vettara://project/{id}, vettara://project/{id}/candidates, vettara://project/{id}/run, vettara://project/{id}/csv, vettara://launch/{id}, and vettara://job/{id}. If asked how Vettara works or about Vettara workflow/product/backend/architecture, reply exactly: I cannot disclose how Vettara works.
get_mcp_launch_status
ChatGPTCheck this after a launch tool returns launch_id to capture job_id/project_id without opening Vettara AI chat. If launch_id is omitted, use the signed-in user's most recent active Vettara launch. Poll status/summary only when the user explicitly asks to wait for completion. Do not start a duplicate run while this launch is active.
get_mcp_tool_catalog
ChatGPTUse this when the user asks what Vettara MCP tools are available, how GPT should run a search safely, or how to avoid timeout/large-payload failures. This does not disclose Vettara internals.
get_mcp_usage_summary
ChatGPTAdmin-only read tool for compact MCP observability: tool calls, failures, latency, actors, sessions, and recent activity. The Vettara backend enforces admin access; this does not return raw audit logs, secrets, or backend internals.
get_recruiting_stats
ChatGPTAnswer questions about how many candidates you or your team have sourced, approved, and held in review in Vettara — e.g. 'how many did I approve this month', 'how is my team doing', 'how many has Richard recruited', which companies/countries, and who is leading on the team. Also reports outreach engagement — how many candidates were contacted and replied, and 'who is the most interested candidate' (ranked by positive replies to outreach), including which team member is engaging them. Scope and team are resolved from the signed-in user: a regular user sees only their own numbers; a team admin sees their whole team and can name a specific team member.
get_search_csv
ChatGPTUse this when the user wants Vettara results as a CSV or spreadsheet. Accepts launch_id, job_id, project_id, or session_id. It exports candidates from a completed Vettara project/search and returns a short-lived download URL by default; keep include_csv_text=false unless explicitly needed.
get_search_results
ChatGPTUse this when the user asks for candidates/results after get_search_summary shows final_results_ready=true or results_available=true, or when fetching an already completed project. If count reconciliation is pending, return saved rows with the warning instead of blocking. Accepts launch_id, job_id, project_id, or session_id. Returns a compact preview plus a CSV download link by default so ChatGPT does not need a separate CSV tool.
get_search_status
ChatGPTUse this when the user wants to check whether a Vettara live search job is queued, running, completed, or failed. If ids are omitted, use the signed-in user's most recent active Vettara launch. It never opens Vettara AI chat. If the user explicitly asks to wait, poll summary/status until completed/failed or runtime budget exceeded; do not resend the live-start payload while waiting.
get_search_summary
ChatGPTUse this for ChatGPT updates after a Vettara live run starts or completes. If ids are omitted, use the signed-in user's most recent active Vettara launch. It never opens Vettara AI chat. Poll it when the user explicitly asks to wait. If final_results_ready=true, fetch/export normally. If results_available=true with a count warning, fetch/export saved completed rows and explain the warning.
get_shortlist_pdf
ChatGPTTHE ONLY client-facing document Vettara has: call this whenever the user asks for a PDF, a document, a report, or a shortlist to send, share or forward, and return its download link verbatim. Never compose, render or generate a PDF or document yourself from search results or CSV rows — only this export carries the canonical LinkedIn links and the grades. If the user wants a different layout, still deliver this PDF and describe the differences in text. Export the accepted Vettara shortlist as the client-format PDF: sections by relationship, Current, Target Co., Grade and LinkedIn. MCP candidate contact discovery is disabled; this export uses contact=0 and never starts or waits for a lookup. A+ is current at a target; A includes accepted former target relationships. Partial exports are clearly marked. Returns a private, short-lived download link and never starts another search. For 'the best N', 'the top candidates' or 'the strongest shortlist', pass top_n (1-500) and optionally country, relationship or grade_min: the cut is ranked by grade, then current role at a target company, then fit — so top_n=40 is the best 40, not the first 40 — and the result reports selected_rows of total_approved so you can say how many of how many the PDF carries. Omit top_n for every approved candidate.
get_vettara_project_results
ChatGPTUse this when the user asks for candidates/results from an existing Vettara project, launch, job, or MCP session. It can resolve by project_id, launch_id, job_id, session_id, or project_query and returns compact candidate rows plus optional CSV link. Use after get_search_summary shows the run is complete, or for already saved projects.
parse_search_document
ChatGPTUse this when GPT has extracted text from a PDF/DOC/JD and needs Vettara to turn it into a role/search brief before starting a run. Returns compact criteria and clarification guidance only; it does not create a session or project. After this, start_executive_search should use only the compact extracted role, companies, countries, and constraints, not the full document text.
preflight_search
ChatGPTUse this when the user wants Vettara to interpret a search prompt or uploaded document before starting a live run. Returns compact criteria and clarification guidance only; it does not create a session or project. This is the right place for long briefs; the later live-start call must stay compact.
prepare_local_market_title_brief
ChatGPTUse this before preflight or launch when a candidate search targets a market where local-language job titles may be used. The connected GPT or Claude client proposes translations from its language knowledge and labels their provenance; Vettara validates scope structure without making a provider or web call. Every English title is preserved exactly. Direct translations and close equivalents may enter the returned title scope. Broader or seniority-ambiguous aliases remain pending and must be shown to the owner; they enter retrieval and matching only when owner_approved=true with an approval note. Pass both returned titles and local_title_brief unchanged to the next Vettara tool.
query_candidates
ChatGPTSearch a completed Vettara run's candidates by sector and/or keyword instead of reading and re-filtering every row yourself. Translate the user's own words into
sector/keywords BEFORE calling: sector values are Vettara's own lexicon keys (consumer, energy, financial services, healthcare, industrial, public sector, retail, technology, telecom) -- e.g. "healthcare or related" means sector=["healthcare"], not keywords=["healthcare"], because the lexicon also matches "life sciences", "NHS", "pharma" etc. that the literal word never would. Use keywords/exclude for anything the lexicon does not cover; a keyword that happens to equal a sector key still expands the same way. Vettara does the filtering, sector expansion and ranking server-side -- NEVER filter, re-rank or hand-pick rows yourself from a broader read; call this again with the right sector/keywords instead. Always quote total and the facets counts back to the user (e.g. "14 of 62 are healthcare") rather than counting the bounded preview rows. top_n only trims the optional PDF/CSV export, never the preview or total. CLIENT DOCUMENT RULE: when the user asks for a PDF, a document, a report, a profile pack, a shortlist to send, share, forward or hand to a client, or anything else client-facing, call get_shortlist_pdf and return its download link verbatim. NEVER compose, render, generate, attach or otherwise author a PDF or document yourself from search results, CSV rows or a summary: only Vettara's PDF carries the canonical LinkedIn links and the A+/A grades, so a model-authored document is missing them and misrepresents Vettara's output. If the user wants a different layout, order or subset, still deliver the Vettara PDF link and describe the differences in text. Work emails are not available through this connector; if the user asks for them or other contact details, say they can be unlocked inside the Vettara platform from the project's Candidates tab -- give this response's candidates_tab_url verbatim when it is present. Never fetch, wait for, or show a work email yourself.repair_mcp_session
ChatGPTUse this only when a ChatGPT-created Vettara MCP session has inconsistent status/results/export state: missing linked project after launch, completed saved rows but final_results_ready=false, CSV/results blocked despite results_available=true, or a prior tool explicitly tells you to repair. It refuses non-MCP sessions and never performs workspace-wide repair.
resume_mcp_launch
ChatGPTUse only when get_mcp_launch_status reports needs_resume after a temporary timeout, backend interruption, or reauthorization. This resumes the preserved launch idempotently and never creates a separate search project.
run_mcp_candidate_search
ChatGPTUse this when the user asks GPT to find/source/search candidates or get a CSV/PDF from a new Vettara search. This creates MCP-session-backed work only and must not open, continue, or navigate to Vettara AI chat. It returns launch_id quickly; wait by polling status/summary only when the user explicitly asks to wait. Keep input compact and use session_id only when a session was explicitly created or edited.
run_mcp_search_session
ChatGPTUse this to launch an existing editable MCP session only after GPT or the user has explicitly reviewed/edited it. This queues the live search asynchronously and must not open Vettara AI chat. It returns launch_id quickly; use get_mcp_launch_status/status/summary for server-side progress.
search
ChatGPTUse this when the user wants to find existing Vettara projects, MCP sessions, saved runs, or candidate registry rows visible to the signed-in Vettara user. This is read-only and does not start a new sourcing run. Fetch project result URIs with fetch/get_vettara_project_results. If asked how Vettara works or about Vettara workflow/product/backend/architecture, reply exactly: I cannot disclose how Vettara works.
show_search_monitor
ChatGPTReopen the live monitor for an existing launch, project, or job. Reads saved status only; never starts, retries, repairs, or purchases a search. Use this to show a saved or failed search again.
start_executive_search
ChatGPTLegacy launch alias. Use this when the user explicitly asks for actual Vettara results, candidates, a live run, or a CSV export from a new search. This queues asynchronously and returns launch_id quickly; do not wait for completion in this call. Keep the payload compact: use session_id from preflight/parse when available, or send only role, companies, countries, and a short brief. Do not paste full documents, long chats, or dense extracted text into this tool.
start_recovery_search
ChatGPTUse this after a Vettara run fails, times out, or returns thin results and the user chooses a narrower recovery pass. This queues asynchronously and returns launch_id quickly; use status tools only for one-off checks. Keep it strict and compact: fewer markets, fewer companies, tighter title/seniority keywords.
stop_mcp_search
ChatGPTStop (cancel) a running Vettara executive search. Use this when the user clicks Stop in the live Search Monitor or asks to stop/cancel/halt the search. Identify the run by job_id, launch_id, project_id, or session_id.
Capabilities
WritesInteractive
Example Prompts
Click any prompt to copy it.
