Recruiterflow

Returns the activity timeline for a single entity - notes, custom activities, meetings (calendar events + meeting/call summaries), and emails - newest first. WHEN TO USE: - "Recent activity on candidate X", "what's happened with X lately". - "Notes on X", "emails with X", "meetings/summaries for X", "custom activities for X". - "Summarize interactions with X" (fetch, then summarize the timeline). WHEN NOT TO USE: - Finding/counting candidates -> search_candidates. - A candidate's current title/company/tags/jobs -> search_candidates enrich=true. - Account-wide activity ("everything logged today") - this is per-entity only. REQUIRED WORKFLOW: 1. Resolve the entity to an id first: candidates via search_candidates. If a name matches multiple, ask which one. 2. Call get_activities with entity_type + entity_id. Optionally pass activity_types to narrow (e.g. only notes). ACTIVITY TYPES: - note: logged notes. - custom: custom activity-log entries (tenant-defined types). - meeting: calendar events (title/time/attendees) plus meeting/call SUMMARIES (summary text, not the full transcript). - email: emails exchanged (subject + body). Candidates only. ENTITY SUPPORT: - candidate: note, custom, meeting, email. (Jobs and other entities are not available yet - calling with an unsupported entity_type returns an error.) RESULTS: Returns {entity_type, entity_id, fetched_count, has_more_available, page, page_size, activities}. fetched_count is the number of activities loaded after merging requested types (NOT the full database total). Results are capped per type at 100 each (notes, emails, custom activities, calendar events, and meeting summaries). When has_more_available is true, tell the user additional activities may exist beyond what was fetched. When fetched_count > page * page_size, paginate with a higher page number to see more within the fetched set. Each activity: {type, time, title, body, author, attendees, source} - fields absent when not applicable (e.g. no attendees on a note). Activities are merged across types and sorted newest first.

get_activities

Lists the account's CANDIDATE custom fields - the resolution tool for filtering on custom fields via search_candidates. WHEN TO USE: - The user references a field that is not in the standard filter catalog ("filter by visa status", "candidates with notice period under 30 days") - it is probably a custom field. - Before building any custom_field.<id> filter. WHEN NOT TO USE: - Standard filters (name, skills, stage, ...) -> get_candidate_filters. - Do not call repeatedly - the field list does not change within a conversation. RESULTS: Returns {custom_fields}: [{id, name, field_type, choices, has_more_choices}]. field_type is one of: text, number, money, date, yes_no, single_select, multi_select. choices lists the valid options for select fields (capped; has_more_choices true when capped). Build the search_candidates filter with key "custom_field.<id>" and the payload shape the custom_field catalog entry documents for that field_type. Match the user's wording to a field NAME here - never guess ids.

get_candidate_custom_fields

Returns the full catalog of filters accepted by search_candidates: for each filter its key, type, allowed conjunctions, value format, detailed usage guidance (when to use, when not to, common phrases, caveats, related filters), and a copy-ready example payload. WHEN TO USE: - Once per conversation, BEFORE the first search_candidates call. - When unsure which filter matches the user's request or how to format its values. - After a search_candidates validation error, to re-check the filter construction. WHEN NOT TO USE: - Job filters -> get_job_filters. - Do not call repeatedly in the same conversation - the catalog does not change. RESULTS: Returns {filters, usage}. Build search_candidates filter objects exactly from the documented examples - send only the documented fields; the server fills in type and status.

get_candidate_filters

Returns the catalog of filters accepted by search_jobs: for each filter its key, type, allowed conjunctions, value format, usage guidance, and a copy-ready example payload. WHEN TO USE: - Once per conversation, BEFORE the first search_jobs call. - After a search_jobs validation error, to re-check filter construction. WHEN NOT TO USE: - Candidate filters -> get_candidate_filters. - Do not call repeatedly in the same conversation - the catalog does not change. RESULTS: Returns {filters, usage}. Build search_jobs filter objects exactly from the documented examples - send only the documented fields; the server fills in type and status.

get_job_filters

Returns candidates in a job grouped by pipeline stage. Supports optional stage filtering and pagination. WHEN TO USE: - "Show me the pipeline for job X." - "Who is in the Interview stage of job X?" - "List candidates in the Sourced stage of the Backend Engineer job." WHEN NOT TO USE: - Searching candidates across multiple jobs -> search_candidates with job filter. - Finding job details -> search_jobs. REQUIRED WORKFLOW: 1. Resolve the job name to a job_id via search_jobs. 2. If the user mentions a stage name, call list_stages(job_id=X) to resolve the stage name to a stage_id (the id field from list_stages). 3. Call job_pipeline with job_id and optionally stage_id. 4. For large pipelines, use page parameter to paginate. RESULTS: Returns {job_id, total_candidates, page, page_size, stages}. Each stage: {stage_name, candidates: [{id, name, highlight_note, entered_stage_at, disqualification_reason}]}. Stages appear in pipeline order. When total_candidates > page_size, tell the user there are more pages. DISPLAY FORMAT: Render ONE markdown table with one row per candidate and these columns in this exact order: Stage | Candidate ID | Name | Entered stage | Note | Disqualification reason. ALWAYS include the Candidate ID column (the candidate "id" field) - never drop it. Keep Stage as its own column and repeat the stage name on every candidate row in that stage - never merge the stage into the Name column. Use "-" for null fields. Show Disqualification reason only for candidates in a disqualified stage. List stages that have no candidates separately below the table as a short note (e.g. "Empty stages: Applied, Recruiter Screen, ...") rather than as blank table rows. COMMON MISTAKES TO AVOID: - Passing a stage name instead of stage_id — always resolve via list_stages first. - Not telling the user about additional pages when total_candidates exceeds page_size. - Dropping the Candidate ID column or merging the stage name into the candidate name column.

job_pipeline

Lists client companies in the account. The resolution tool for turning company names into numeric IDs required by the job_client_company filter on both search_candidates (candidates tied to a company through their job) and search_jobs (jobs belonging to a company). WHEN TO USE: - Before building job_client_company filters (their values are company IDs). - When the user asks about companies in the system. WHEN NOT TO USE: - Searching candidates by name -> search_candidates with name filter. - Searching jobs -> search_jobs. COMMON USER REQUESTS: - "Candidates at Morgan Stanley" (resolve -> job_client_company filter on search_candidates). - "Jobs for Google" (resolve -> job_client_company filter on search_jobs). RESULTS: Returns {companies}: [{id, name}]. Use the id in filter values.

list_companies

Lists pipeline stage names. The resolution tool for turning stage mentions ("screening", "interview") into the exact stage names that candidate stage filters require. WHEN TO USE: - Before building stage, stage_in_job, or job_stage_passed_through candidate filters. - When the user asks what stages exist in a pipeline. WHEN NOT TO USE: - Job statuses (Active/Won/Lost) are NOT pipeline stages - those come from search_jobs results. USAGE: - Pass job_id (resolved via search_jobs) to get that specific job's stages in pipeline order - ALWAYS do this when building stage_in_job. - Omit job_id to get distinct stage names across all jobs. RESULTS: Returns {stages}: [{id, name, job_id, ranking}]. Stage names must be used EXACTLY as returned - pick the closest match to what the user said ("screening" -> "Recruiter Screen") and never guess names that are not in the list.

list_stages

Lists Recruiterflow team members. The resolution tool for turning a person's name into a numeric user ID. WHEN TO USE: - Before building lead_owner or added_by candidate filters (their values are "User.<id>"). - To resolve posted_by_id from search_jobs results into a person's name. - When the user asks who is on the team. WHEN NOT TO USE: - Searching candidates by name -> search_candidates with the name filter (candidates are not team members). COMMON USER REQUESTS: - "Candidates owned by Tarun" (resolve Tarun -> User.<id> -> lead_owner filter). - "Who posted this job?" (match posted_by_id from a job result). RESULTS: Returns {users}: [{id, name, email, deleted}]. Includes deactivated (deleted: true) members by default since historical records may reference them - set include_deleted=false to exclude. COMMON MISTAKES TO AVOID: - If multiple users match the mentioned name, ask the user which one - never pick silently. - Filter values need the "User." prefix plus the id from this tool, e.g. "User.226483".

list_users

Primary tool for finding, counting, and retrieving candidate records from Recruiterflow. Mirrors the Recruiterflow Advanced Candidate Search - results and counts always match what users see in the app. Use whenever the user asks about candidates, candidate counts, ownership, locations, pipeline status, stages, jobs, sourcing activity, or any candidate-related reporting. WHEN TO USE: - Find candidates matching specific criteria. - Count candidates matching criteria ("how many ..."). - List candidates owned by or added by a team member. - Search candidates in specific jobs or stages. - Search candidates by location (city/state/country or radius). - Find active or inactive candidates. - Generic candidate queries ("find X", "details for X", "tell me about X") -> pass enrich=true to get full profiles with title, company, LinkedIn, tags, and custom fields. WHEN NOT TO USE: - Looking up team members -> list_users. - Looking up jobs or job details -> search_jobs. - Looking up pipeline stage names -> list_stages. - Learning available candidate filters -> get_candidate_filters. REQUIRED WORKFLOW: Before the first candidate search in a conversation, call get_candidate_filters to learn the valid filter keys, conjunctions, and value formats. If a filter requires IDs or system values, resolve them first: - lead_owner / added_by -> list_users (values are "User.<id>"). - custom fields ("visa status", "notice period", ...) -> get_candidate_custom_fields (key becomes "custom_field.<id>"). - job / stage_in_job -> search_jobs (values are numeric job IDs). - stage / stage_in_job / job_stage_passed_through -> list_stages (values are exact stage names). - job_client_company (company) -> list_companies (values are numeric company IDs). Never guess IDs or stage names. If a name resolves to multiple users/jobs, ask the user which one they meant. FILTER SEMANTICS: - Filters combine using match-all (AND, default) or match-any (OR). - Values within a single filter always act as OR. - Text matching is case-insensitive SUBSTRING matching ("tony" finds "Tony Stark") - first names alone are fine. - Empty filters array returns all candidates visible to the user. COMMON USER REQUESTS: - "Show candidates owned by Tarun." (list_users -> lead_owner) - "How many active candidates do we have?" (active_candidate_pipeline_status) - "Find engineers in Bengaluru." (location_city) - "Who is in the Interview stage of the Backend job?" (search_jobs + list_stages -> stage_in_job) - "Candidates within 30 km of Mumbai." (radius_search) - "Who completed Recruiter Screen?" (job_stage_passed_through) RESULTS: Returns {count, candidates}. count is always the EXACT total of matching candidates, even when the returned list is capped by the limit parameter (default 50). For counting questions, always read the count field - never count returned records manually. When the list is capped, tell the user the total. Each candidate: {id, name, email, phone, city, state, country, location}. When enrich=true, the first 5 candidates also include a basic_profile object with emails, phones, current_title, current_company, linkedin, added_by, lead_owner, tags, and custom_fields (list of {name, value} objects). Display every custom field with its EXACT name verbatim — never rename or summarize them. Do NOT set enrich for specific questions like "which job is X in" or counting queries. COMMON MISTAKES TO AVOID: - Passing names instead of "User.<id>" values to lead_owner / added_by. - Passing job names instead of numeric IDs to the job filter. - Combining separate job + stage filters when the user means stage-within-job (use stage_in_job). - Counting the returned list instead of reading count. - Retrying a 0-result search with shorter fragments instead of re-checking the filter construction and asking the user.

search_candidates

Primary tool for finding and retrieving job records from Recruiterflow. Mirrors the Recruiterflow job Advanced Search. WHEN TO USE: - "Details of the X job" questions. - Resolving a job name to its numeric ID before building the job or stage_in_job candidate filters. - Browsing or counting jobs ("show me all jobs", "how many jobs do we have"). WHEN NOT TO USE: - Finding candidates in a job -> resolve the job ID here, then search_candidates. - Learning available job filters -> get_job_filters. REQUIRED WORKFLOW: Call get_job_filters once per conversation before the first job search. The name filter matches by case-insensitive SUBSTRING ("backend" finds "Backend Engineer"). Empty filters array returns all jobs visible to the user - use that to browse or to suggest close matches after a 0-result name search. If a filter requires IDs, resolve them first: - job_client_company -> list_companies (values are numeric company IDs). - job_visibility -> use visibility IDs directly (see filter catalog). COMMON USER REQUESTS: - "Give me details of the Backend Engineer job." - "Find the TCS role." - "Candidates in the X job" (resolve ID here first). RESULTS: Returns {count, jobs}. count is the exact total even when the list is capped by limit (default 50). Each job: {id, name, open, visibility, client_company, status, posted_by_id}. posted_by_id is a numeric user ID - resolve it to a person via list_users only when the user asks who posted the job. COMMON MISTAKES TO AVOID: - If multiple jobs match a name, ask the user which one before using the ID. - Do not treat status (Active/Won/Lost...) as open/closed - the open boolean is separate.

search_jobs