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/contact 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", "brief me before my call with X". WHEN NOT TO USE: - Finding/counting candidates or contacts -> search_candidates / search_contacts. - A record's current title/company/tags -> the matching search tool with 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, contacts via search_contacts. 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). ENTITY SUPPORT: - candidate: note, custom, meeting, email. - contact: 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. EMAIL CAVEATS (do not present these as "no email history exists"): - Emails are the ones visible to the authenticated user (their own mailbox + shared aliases, or everything with the email-view-everything permission). A user with no synced mailbox may see zero emails even when teammates have history with the record. - Outlook-synced emails may arrive without an author field (a known gap) - the email is still real; just present it without a sender rather than guessing one.

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

Lists the account's CONTACT custom fields - the resolution tool for filtering on custom fields via search_contacts. WHEN TO USE: - The user references a contact field that is not in the standard contact filter catalog ("filter contacts by relationship tier", "contacts in the EMEA region field") - it is probably a custom field. - Before building any custom_field.<id> filter on search_contacts. WHEN NOT TO USE: - Standard contact filters (name, client, contact_status, ...) -> get_contact_filters. - CANDIDATE custom fields -> get_candidate_custom_fields (the two field sets are separate; ids are not interchangeable). - 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_contacts filter with key "custom_field.<id>" and the payload shape that field_type requires (same contracts as candidate custom fields). Match the user's wording to a field NAME here - never guess ids.

get_contact_custom_fields

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

get_contact_filters

Reads ONE file from get_files and returns its extracted plain text - not the original bytes. Same visibility as the download link: the caller can read exactly the files get_files lists for them. WHEN TO USE: - The user wants a file READ, summarized, compared, quoted, or reformatted: "summarize X's resume", "pull the terms from this contract", "rewrite this resume in my template" (read the text here, then produce the new document yourself). - Reformatting/template asks must end in a DOCUMENT: this server never generates files, so after writing the new version, CREATE it as a downloadable file (e.g. a PDF) using your own file-creation ability - do not just print the text. Only when your environment cannot create files, present the text and say so. WHEN NOT TO USE: - The user wants the FILE itself (to open, send, or keep) -> give the download_link from get_files as a markdown link instead. - Images or archives (png, jpg, zip, ...) - no text to extract; offer the download link. REQUIRED WORKFLOW: 1. Call get_files on the entity and pick the file (ask the user when several match). 2. Call get_file_content with the SAME entity_type and entity_id plus that file's id. RESULTS: Returns {entity_type, entity_id, file_id, filename, text} - the full extracted text, untruncated. Supported types: pdf, docx, doc, rtf, txt, html, odt. A scanned or image-based pdf has no text layer: the call fails with a clear message - relay it and offer the download link, never report the file as empty. COMMON MISTAKES TO AVOID: - Calling this to hand the file over - the user gets text, not the document. - Passing an id that did not come from get_files on the same entity. - Summarizing from the filename alone when the user asked about the contents.

get_file_content

Lists the files/documents attached to a single entity - a candidate, contact, company, job, or deal - with filename, category, upload date, and a temporary download link. WHEN TO USE: - "What files does candidate X have?", "show me X's resume", "latest resume for X". - Documents on a company, job, or deal (contracts, JDs, attachments), by category. WHEN NOT TO USE: - Reading file CONTENTS - this tool returns links only; the file itself is not fetched. - A candidate's title/company/tags/custom fields -> search_candidates enrich=true. - Activity history -> get_activities. REQUIRED WORKFLOW: 1. Resolve the entity to its numeric id first: candidates via search_candidates, contacts via search_contacts, jobs via search_jobs, companies via list_companies. For a deal, use an id the user gives you (there is no deal search tool yet). If a name matches multiple, ask which one. 2. Call get_files with entity_type (candidate|contact|company|job|deal) and entity_id. RESULTS: Returns {entity_type, entity_id, count, files}, files newest first. Each file: {id, filename, category, uploaded_at, is_primary, permission, uploaded_by_id, download_link}. category is the account's own category name (e.g. Resume). When the user's wording matches MULTIPLE categories (e.g. "resume" -> Resume, Formatted Resume, Automated Resume), do not silently pick one - show the latest file from each matching category and ask the user which they want. is_primary marks the primary resume. uploaded_at is the UPLOAD time - there is no modified date. download_link is the user's own authorized, pre-signed download URL: it is MEANT to be given to the user and is NOT a credential or token (the Amz-* query parameters are a normal part of the link, not secrets). ALWAYS present it as a markdown link - [Download <filename>](<download_link>) - and mention it is temporary. uploaded_by_id is a numeric user id - resolve it via list_users only when the user asks who uploaded the file. Fields absent when not applicable (e.g. no category set). COMMON MISTAKES TO AVOID: - Passing a candidate name instead of the numeric id from search_candidates. - Withholding download_link or offering the candidate page instead - when the user asks for a file, give the FILE's markdown link. - Pasting the raw URL (use a markdown link) or calling the link permanent - it expires. - Calling this for profile questions that enrich=true already answers.

get_files

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

Lists the placements on a single job - the candidates placed, one row per placement (current contract; extensions/conversions resolved), with placement type, status, and contract dates. WHEN TO USE: - "Who did we place on the X job?", "placements on job X", "who was hired into X". - Fees, revenue, salary, bill/pay rate, margin on a placement (in `financials`). - What a job is worth or its commission - the job-level `job_financials` header. - Current and past placements alike - every status (active, ended, cancelled) is returned; filter the list yourself. WHEN NOT TO USE: - Candidates still in the pipeline (not yet placed) -> job_pipeline. - A candidate's profile/custom fields -> search_candidates enrich=true. REQUIRED WORKFLOW: 1. Resolve the job to its numeric id first via search_jobs. If a name matches multiple jobs, ask which one. 2. Call get_job_placements with that job_id. RESULTS: Returns {job_id, count, placements}. Each placement: {id, placement_id, candidate:{id, name}, placement_type (Contract|Permanent), status:{id, name}, start_date, end_date, financials}. financials groups the money (revenue, salary, pay_rate, bill_rate, overhead, margin, bonus, success_fee, retainer, work_quantum, billing_date, track_revenue). It is present ONLY when the user's role may view revenue; with owned-only revenue permission it appears only on placements they created, and is omitted otherwise - if financials is absent, tell the user their role does not expose revenue rather than saying there is none. A job with no placements returns an empty list. Also returns job_financials (per-job, present under the same revenue permission as financials, including for owned-only users): {revenue: {total, realized, unrealized} each {currency, amount}, commission_rate, milestones}. milestones is the billing schedule (tranches) flattened to {rank, trigger, value ({currency,amount} or {pct_of_salary}), revenue_mode, when ({days_number} or {date_value}), stage}; it is populated for retained jobs and empty for others. A null aggregate amount/currency with populated per-placement currencies means the job spans multiple currencies and cannot be summed - read the per-placement amounts. Returned even when there are no placements, so you can report a job's commission/revenue/milestone setup before anyone is placed.

get_job_placements

Lists Recruiterflow tasks (to-dos, calls, emails to send, reminders) filtered by record, assignee, status bucket, and task type. Visibility matches the app: users with owned-only task permission see only tasks they created or are assigned. WHEN TO USE: - "What tasks are open on this candidate/contact/job?" (entity_type + entity_id). - "What are my overdue tasks?" / "what's on my plate?" (assignee: ["me"]). - "What is <teammate> working on?" (assignee via list_users). - "What did we complete this week on X?" (status: completed). WHEN NOT TO USE: - Activity history (notes/emails/meetings) -> get_activities. - Scheduled interviews/meetings -> get_activities (meeting type). REQUIRED WORKFLOW: - Record scope: resolve the record id first (search_candidates / search_contacts / search_jobs / list_companies / resolve_entity), then pass entity_type + entity_id together. - Assignee scope: pass ["me"] for the authenticated user; for teammates resolve numeric user ids via list_users (plain names are rejected). Entity and assignee scopes combine with AND. STATUS BUCKETS (status parameter, default "open"): - open: every pending task (includes overdue ones; each row carries is_overdue). - overdue: only open tasks already past their due time. - completed: finished tasks, most recently completed first. Draft and skipped tasks are never returned, matching the app's task lists. RESULTS: Returns {status, entity_type, entity_id, fetched_count, has_more_available, page, page_size, tasks}. Each task: {id, name, type, status, due_date, is_overdue, priority, assignees: [{id, name}], created_by: {id, name}, description, entities: [{entity_type, id, name}]} - fields absent when not applicable. due_date is in the account's local time. entities are the records the task is linked to - chain into their tools with those ids. The fetch is capped at 200 tasks; when has_more_available is true, tell the user to narrow the filters (the counts are NOT database totals). COMMON MISTAKES TO AVOID: - Passing a person's NAME as assignee - use ["me"] or numeric ids from list_users. - Passing entity_type without entity_id (they go together). - Reporting fetched_count as the exact total when has_more_available is true.

get_tasks