Tool reference

Call this FIRST in a new conversation, or whenever the user asks how to begin ('set me up', 'where do I start', 'what's the state of things'). One read returns the workspace's maturity (activated? jobs? candidates? automations? ATS connected?) plus the recommended next steps — no need to probe with empty list calls.

Call this when you need the org's departments, candidate sources, or rejection/close reasons (e.g. before creating a job or rejecting with a reason).

Call this once when an org is brand new ('set me up') — seeds default sources, reasons, and the standard pipeline template. Idempotent and safe to re-run.

Call this before drafting any job description or public-facing copy — returns the company's values, what makes a great employee here, work style, and voice notes. If unset, run the culture intake (see set_culture_profile).

Call this after interviewing the user about their culture — typically during first-run or before the first posting. Ask: what 3-5 values actually drive decisions here (not poster slogans)? Describe your best employee — what do they do that others don't? What's the working style (remote posture, pace, collaboration)? How should we sound when we write on your behalf? The profile feeds job drafting, the public board concierge, and the apply experience. internalNotes never reach public surfaces.

values · goodEmployee · workStyle · voice · internalNotes

Call this when the user names a department that doesn't exist yet (check list_org_structure first). Departments organize jobs ('Analytics', 'Engineering'); pass the returned id as create_job's departmentId. Admin only.

name · parentId

Call this when the workspace has no logo or the recruiter wants to change it ('use the logo from our website'). Pass a public https image URL — the server fetches, validates (PNG/JPEG/WebP/SVG, max 1MB), and re-hosts it on our storage (candidate emails never hotlink external URLs). The logo then appears on the hosted job board and in every candidate-facing email. If no good URL exists, point the recruiter at the upload control: {appHost}/orchestrator/settings#branding.

imageUrl

Call this when the recruiter asks about their jobs, roles, or requisitions (e.g. 'what's open?', 'show my jobs'). Returns compact rows {id, title, status}; use get_job for full detail.

status · cursor

Call this for full detail on one job (description, compensation, status, dates).

jobId

Call this when the recruiter asks how a job's pipeline looks ('how's the PM role doing?', 'where are candidates stuck?'). Returns per-stage active candidate counts in order.

jobId

Call this when the recruiter wants to open a new role/requisition. IMPORTANT: do not call this from a bare title. First run a short intake — ask what makes a great candidate (3-4 must-haves), seniority and location/remote posture, and whether they have an existing JD or a similar posting to paste; ALSO call get_culture_profile and blend the values + good-employee traits + voice into the draft. Then show descriptionPlain and confirm before creating. A title-only job produces a weak posting and a weak assessment match. Stages come from the org's default pipeline template automatically.

title · departmentId · descriptionPlain

Call this to edit an existing job's title, description, or department ('add a culture fit section to the Data Analyst JD'). If the job is published, call publish_job_posting afterward — republishing refreshes the public posting from the job's new content.

jobId · title · descriptionPlain · departmentId

Call this when the recruiter wants application screening or knockout questions on a job ('ask applicants if they can work onsite in Austin'). DRAFT the questions WITH the recruiter and show the full set before calling — this replaces the job's whole question list. Questions probe eligibility, logistics, and skills ONLY (never protected characteristics — the server rejects prohibited probes). A knockout (boolean/select answers listed in `knockout.disqualifying`) only FLAGS the application for human review with evidence; nothing is ever auto-rejected or hidden. Applicants see the questions but never which answers disqualify. Tag factual questions with `fact` (location / language / work_authorization) — those answers ride any later assessment so the candidate confirms instead of re-answering.

jobId · questions

Call this to read a job's current screening/knockout questions before editing them (set_screening_questions replaces the whole list).

jobId

Call this to open, close, or archive a job. Closing accepts an optional closeReasonId from list_org_structure.

jobId · status · closeReasonId

Call this to publish a job on the org's public hosted board ('post the PM role'). Returns the public URL where candidates apply directly — applications land in the job's first stage automatically. Re-calling republishes.

jobId

Call this to take a job off the public board ('stop accepting applications for the PM role'). The posting URL stops resolving; existing applications are unaffected.

jobId

Call this when the user asks for a social/LinkedIn post to share a role ('write me a LinkedIn post for the Senior PM role', 'help me share this opening'). Returns two ready-to-share drafts — one in the recruiter's own voice (to share from their profile) and one in the company's voice (for the company page) — each with a tracked apply link so applies are attributed. The role must be published to the public board first. These are DRAFTS for the human to review and post; nothing is posted automatically.

jobId

Call this AFTER a role is published to push it out to free job-distribution channels ('distribute the PM role to Google and Indeed', 'get this role on the job boards'). Channels today: 'google' (Google for Jobs) and 'indeed' (the aggregator feed that reaches Indeed-style boards). This is CONSEQUENTIAL — it returns a distributionId you can pass to withdraw_distribution to reverse it. The role must be published first. Confirm with the user before distributing; never distribute silently.

jobId · channels

Call this to reverse a distribute_posting ('take the PM role off the job boards'). Pass the distributionId returned by distribute_posting (it equals the jobId). Removes the role from every channel it was distributed to.

distributionId

Call this to see which distribution channels a role is currently live on ('where is the PM role posted?'). Returns the channels + when it was distributed, or null if it hasn't been distributed.

jobId

Call this when the recruiter refers to a person by name or email ('move Maya forward', 'do we have anyone from Acme?'). Returns compact matches; use get_candidate for the full profile.

email · name

Call this for one candidate's full ATS profile: identity, links, tags, recent notes.

atsCandidateId

Call this to add a person to the ATS ('add Jane, jane@x.com, from the meetup'). Dedups by email — an existing candidate is returned instead of a duplicate.

name · primaryEmail · currentTitle · currentCompany · sourceId

Call this to record context on a candidate ('note that she prefers remote'). Markdown supported.

atsCandidateId · bodyMarkdown

Call this to label a candidate ('tag him as senior-backend'). Creates the tag if new.

atsCandidateId · tag

Call this for 'what have we sent this candidate' or any communication-history question. One timeline of every email we sent them (receipts, sequence steps, rejection notices, invites) and every reply they sent back, newest first.

atsCandidateId

Call this for an audit, EEOC, or data request about a specific candidate. Returns the full records bundle: profile, every application with screening answers and decision records, notice states, and the complete comms log. Admin only, and the export itself is audit-logged.

atsCandidateId

Call this ONLY after the recruiter confirms two records are the same person. Irreversibly folds the duplicate into the primary (notes, files, tags move; emails union).

primaryId · duplicateId

Call this for the candidates on a job (optionally one stage), or recent activity across the org ('who applied this week?' → updatedAfter). Compact rows; use get_application for detail.

jobId · stageId · status · updatedAfter · cursor

Call this for one application's detail including its full stage history.

applicationId

Call this to put a candidate into a job's pipeline. If they already have an application there, the existing one is returned/reactivated — never a duplicate.

jobId · atsCandidateId · sourceId

Call this to advance or move a candidate's application to another stage ('move Maya to onsite'). Returns a transitionId you should mention to the recruiter as the undo reference. Moving to a terminal rejected stage requires reject_application instead when a reason is needed.

applicationId · toStageSlug · toStageId · note

Call this to move a candidate's application to a DIFFERENT job (not a stage change). The application restarts in the target job's first stage.

applicationId · toJobId

Call this ONLY after the recruiter explicitly confirms rejecting a specific candidate. Never bulk-reject. Requires a rejectReasonId from list_org_structure. Moves to the terminal rejected stage.

applicationId · rejectReasonId · note

Call this when anyone asks 'why was this candidate rejected' or for an audit/EEOC question. Returns the full decision record: who confirmed, when, the reason, the exact evidence the human was shown, and the notice state.

applicationId

Call this when the recruiter wants to hold a not-yet-sent rejection email ('don't send Maya the rejection yet'). Only cancels pending notices — a sent email cannot be unsent. Reactivating an application cancels its notice automatically.

applicationId

Call this when the recruiter wants to clear out flagged applicants in bulk ('reject everyone who failed the location knockout'). Builds an evidence-backed proposal from triage flags (max 25, expires in 24h) — it changes NOTHING about any application. Present every candidate's name + evidence to the recruiter verbatim, then call confirm_rejection_batch only with the ids they explicitly approved.

jobId · applicationIds

Call this ONLY after the recruiter reviewed the proposal list and explicitly approved specific candidates — repeat every name back before calling. Actor-bound: only a signed-in recruiter's grant can confirm; API keys and automations are refused. Each confirmed id flows through the same single rejection path as reject_application (reason required). Optional sendNotice schedules the rejection email after a delay (default 2 days — the undo window).

proposalId · confirmedApplicationIds · rejectReasonId · note · sendNotice · noticeDelayDays

Call this to send a candidate the HiringTest assessment for their job ('send Maya the assessment'). The job must have an assessment attached. Idempotent — re-calling resends the same link as a reminder. Moves the application into the assessment stage.

applicationId

Call this when the recruiter asks how a candidate scored ('how did Maya do?'). Returns the composite score, domain breakdown, and a scorecard link. Returns available:false if they haven't completed the assessment yet.

applicationId

Call this to invite a candidate to build a HiringCase living profile (verified endorsements + demonstrated work). It's an offer, not a requirement — phrase it to the recruiter that way. Idempotent: won't re-send within 30 days or to someone who already has a case.

atsCandidateId

Call this before attach_assessment to see which activated HiringTest assessment roles this workspace can attach to a job. Empty = the user needs to activate a role in HiringTest first.

Call this to make a HiringTest skill assessment the job's native assessment stage ('use the PM assessment on this req'). roleId is an activated HiringTest role in the same workspace. Once attached, send_assessment works and completed scores flow back automatically.

jobId · roleId

Call this before submitting feedback to find the right scorecard form, or when the user asks what feedback forms exist.

Call this when the signed-in interviewer wants to file their scorecard on an application. Recruiter-actor only — an API key cannot file feedback as nobody. Others' feedback on the application stays hidden until the caller has submitted theirs (bias control).

applicationId · interviewId · formId · values · overallRecommendation

Call this to record an interview time agreed with the candidate ('book Maya's onsite for Tuesday 2pm'). Emails each interviewer the details + a calendar link. Time is ISO 8601 with timezone.

applicationId · interviewId · scheduledAt · durationMinutes · location · interviewerRecruiterIds

Call this when an interviewer asks to be prepped ('prep me for my 2pm') — returns candidate background, the job, this interview's focus, the HiringTest assessment evidence (composite + weakest domains to probe), and any visible prior feedback.

scheduleId

Call this to summarize how a candidate looks across BOTH signals at once: the AI assessment composite + domain scores AND the human interview feedback (recommendation tally + per-dimension means), plus whether the current stage's feedback gate is satisfied. Summarize, do not decide — never recommend a hire or reject; the human decides. A pre-submit interviewer sees the AI side but a blinded human side (bias control).

applicationId

Call this to ask a named teammate to file their interview scorecard on a candidate ('ask Dana to screen Alex'). Addressed by the reviewer's email — they must be a teammate in this workspace. Emails them the request. It ASKS for a screen; it never files one and never makes a hiring decision.

applicationId · reviewerEmail · interviewId · dueAt

Call this to require a human screen before a candidate can move forward out of a stage ('no one moves past Onsite until Dana's screen is filed'). Admin only. OFF by default; configured per job + per stage. Optionally scope to specific reviewer emails. It BLOCKS the forward move until the required feedback is filed — it never declines or moves anyone, and never fires for automated moves or rejections. Pass enabled:false to clear the gate for that stage.

jobId · stageSlug · enabled · reviewerEmails

Call this to draft an offer on an application ('draft an offer for Maya at 180k'). Terms are versioned immutably — updates append a new version. The draft does NOT reach the candidate until extend_offer.

applicationId · title · startDate · salary · equity · bonus · notes

Call this to send a draft offer through the company's sequential approval chain. No chain configured = the offer auto-approves (small-team default). Each approver is emailed when their step comes up.

offerId

Call this ONLY when the signed-in recruiter is the named approver of the current pending step and has stated their decision. Actor-bound: an API key or agent cannot approve on someone's behalf — if the caller isn't the named approver this fails. Rejection returns the offer to draft with the note.

offerId · decision · note

Call this to send the approved offer letter to the candidate by email ('send Maya her offer'). Consequential — the candidate sees it. Requires the offer to be approved.

offerId

Call this when the candidate has responded to an extended offer. Accepted moves the application to the hired terminal stage and fires candidate.hired. Declined just records the status.

offerId · response

Call this ONLY on an explicit instruction to pull an extended offer. Destructive — confirm with the user before calling; this is visible to the candidate relationship even though no email is sent automatically.

offerId · note

Call this AFTER drafting an outreach sequence WITH the user. Authoring contract: call get_culture_profile first and write every step in the company's voice; at most 4 steps with 2+ day gaps; show the user every step's subject and body and get explicit confirmation BEFORE calling. Step 1 sends on enrollment (delayDays 0). The engine appends a non-removable unsubscribe footer; sequences stop automatically when the candidate replies. Writing rules apply (no em dashes, no hype).

name · jobId · steps

Call this when the user asks about their outreach sequences, or before enrolling candidates (to pick the right sequenceId).

Call this to start outreach to specific candidates ('enroll these five in the data-analyst three-touch'). Returns a PER-CANDIDATE outcome — some may be blocked (opted out, contacted within the 30-day window, no email, already enrolled); report every block reason to the user, never retry around them.

sequenceId · atsCandidateIds

Call this to stop outreach to one candidate ('stop the sequence for Maya'). Consequential; remaining steps are cancelled, nothing is deleted.

enrollmentId

Call this when the user asks how a sequence is performing. Reports enrollments by state, steps sent, replies, and interested-classified replies. Lead with replies and interested counts when summarizing.

sequenceId

Call this when a candidate asks not to be contacted ('take Maya off all outreach'). PERMANENT: it blocks all current and future sequence sends for them; only an admin can reverse it. Transactional mail (application receipts, offers) is unaffected.

atsCandidateId

Call this to see the workspace's automation rules ('what automations do we have?'). Returns each rule's trigger, actions, scope, and enabled state.

Call this when the recruiter asks to automate routine pipeline motion ('whenever someone scores 80+, move them to interview and tell me'). Triggers: application.created, application.stage_changed (optionally filtered by toStageSlug/toStageType), application.assessment_completed (optionally minScore/maxScore), application.stale (daysInStage), sequence.reply_interested (a candidate's reply to an outreach sequence was classified interested). Actions are a CLOSED set: move_stage, add_tag, add_note, notify, send_assessment — there is deliberately NO reject action; automations never make hiring decisions. Admin only.

name · jobId · trigger · actions

Call this to pause or resume an automation rule. Admin only.

ruleId · enabled

Call this to promote a connected ATS's full pipeline into Orchestrator ('import everything from Greenhouse'). Returns a runId; it first inventories + proposes a stage mapping for the recruiter to confirm — NO records are written until confirm_ats_import is called.

connectionId

Call this AFTER the recruiter has reviewed the stage mapping from get_ats_import_status, to begin writing the imported jobs, candidates, and applications. Idempotent.

runId

Call this to check an import run: its status, the proposed stage mapping + any per-entity gaps (when awaiting confirmation), and live counts. Returns the mapping for the recruiter to review before confirming.

runId

Call this when the user asks how hiring is going, pipeline health, time-to-fill, sequence reply rate, or source effectiveness. Returns the company-wide rollup (funnel + stage conversion, time-in-stage, time-to-fill, sequence engagement, source effectiveness, assessment quality, rejection volume) plus plain-language observations. Pass jobId to narrow to one job. For a single job's stage counts use get_pipeline_summary; for one sequence use get_sequence_metrics. Observability only — it never recommends a hiring decision; PostHog-derived numbers are flagged approximate.

jobId

Call this when the user asks what a hire costs, cost per hire, hiring spend, cost by department or source, or where recruiting money goes. Returns the fully-loaded cost per hire (recruiting spend plus internal time), the external-vs-internal split, cuts by department / source / recruiter / category, a monthly time series, plus plain-language observations. Observability only, relative to the company's own portfolio — it never recommends cutting spend or a hiring decision; some figures are benchmark estimates when comp is not entered. Admin-only.

departmentId · jobId

Call this when the user describes how they hire (the stages, who interviews, roughly how long) so we can estimate the internal cost of a hire. Returns a DRAFT of stages with estimated interviewer hours — review it with the user, then call save_hiring_process to persist. Does not save on its own. Admin-only.

description · label · scope · departmentId · roleId

Call this after the user confirms a hiring-process draft (from define_hiring_process). Persists the reusable process artifact that drives interviewer-effort cost. Pass an id to update an existing one. Admin-only.

id · label · scope · departmentId · roleId · stages

Call this to record a recruiting-spend line item (job board, agency fee, tooling, referral bonus) over a period. Feeds cost-per-hire. Pass an id to update. Admin-only.

id · category · amountCents · periodStart · periodEnd · departmentId · sourceId · jobId · currency

Call this to record the loaded cost of a recruiter or interviewer. Leave baseAnnualCents out to accept a benchmark estimate keyed by benchmarkKey; allocationPct is the share of their time on recruiting. Feeds the internal cost of a hire. Pass an id to update. Admin-only.

id · label · baseAnnualCents · benchmarkKey · loadingMultiplier · allocationPct · recruiterId · departmentId · effectiveFrom · effectiveTo