Hireinator

Stops an apply link: the public form answers not found and nobody can apply through it. Applications already in stay on the Resume screening page. create_apply_link on the same position reopens it with a new URL, keeping its applications.

close_apply_link

Creates the public application form for an open position and returns its URL (list_apply_links shows it again; give it to the user to post on the job ad). Anyone holding the link can apply: a candidate enters their name, email and an optional LinkedIn link, attaches a resume and consents; the resume is screened like an upload and appears on the Resume screening page marked Applied, with the applicant's own identity. Each application sends the applicant a confirmation email. One link per position; a position whose link is closed gets a fresh URL. The public description defaults to the position's description. The form always asks for first name, last name, email, a resume and consent (LinkedIn optional); the company may add up to 8 questions of its own (short text, long text, yes/no, a pick list), each optionally required, and "How hiring works" steps. The page also shows the role facts set on the position (update_position facts: location, work mode, employment type, experience, salary when shown, skills). Emails nobody at creation.

create_apply_link

Creates an assessment as a DRAFT from challenge ids (from list_challenges, list_assessment_templates or recommend_assessment). A draft cannot be sent to candidates until publish_assessment. Emails nobody and spends nothing. It is not linked to any position: to make it a position's test, set it as the position's default assessment with update_position (check get_position first, the position may already have a test with candidates on it).

create_assessment

Creates a company-wide candidate tag. Apply it with set_candidate_tags. Tags are team-only, never shown to candidates or clients.

create_candidate_tag

Creates a challenge owned by the company. Coding challenges need functionName, inputTypes, outputType, languageTemplates and testCases (each input line is one function argument); MCQ needs mcqQuestions; agentic and take-home challenges use their own fields. Check get_challenge_for_edit on a similar library challenge for the shape. Emails nobody.

create_challenge

Adds a client company to an agency account (a label; clients have no login). Searches are confidential by default: candidates see only the agency. Set revealToCandidates true only when the user explicitly says the client may be named to candidates.

create_client

Creates a job opening. The description is Markdown (bold, italic, ## headings, - and 1. lists); screening notes guide AI resume screening and the assessment recommendation. Set defaultAssessmentId so invites and the position's assessment stage use that test. Emails nobody and spends nothing.

create_position

Creates a preview link that shows one person (a lead, a hiring manager) up to five questions exactly as a candidate sees them, plus anonymous sample reports, and returns the URL (list_preview_links shows it again; give it to the user to send). Nothing on the page is timed, scored, recorded or billed, and it is not a candidate invite. The label is who it is for, as the page says it ("Michael at Seekr"): a first name and a company, never an email. The page shows no person's name and not the company that made it. Questions are library challenges or the company's own, from list_challenges. Links expire after 7 days by default (1 to 30 days) and can be revoked.

create_preview_link

Publishes a shortlist of completed, fully graded candidates to one agency client as a public link the client opens without a login, and returns that URL once (it cannot be retrieved later; give it to the user to send). Anyone holding the link can see the shared candidates, and it now sits in this conversation; revoke_shortlist_share turns it off. The client sees skill grades and the resume fit; candidate email (showContact) and integrity signals (showIntegrity) are shown only if switched on, both off by default. Confirm candidates and switches with the user first.

create_shortlist_share

Permanently deletes ARCHIVED candidates now (sessions, submissions, results), instead of waiting for the 30-day purge. Cannot be undone; live (not archived) candidates in the list are skipped without an error, so archive them first with archive_candidates. Company admins only. Returns the number of test sessions deleted (a candidate with two tests at a position counts 2; a journey with no test counts 0), not the number of ids you sent; a live id deletes nothing, so tell the user which ones were not archived.

delete_archived_candidates

Deletes a candidate note. Only its author (or a company admin) may delete it. The id comes from list_candidate_notes.

delete_candidate_note

Deletes a candidate tag and removes it from every candidate that carries it. The id comes from list_candidate_tags.

delete_candidate_tag

Permanently deletes one of the company's own challenges with its test cases. Library challenges cannot be deleted. Confirm with the user first.

delete_challenge

Permanently deletes an agency client. Refused while any position, candidate session or shortlist references it; use archive_client instead in that case.

delete_client

Permanently deletes a position with its hiring process and every candidate's stage history at it. Candidate sessions and test results are kept. Closing it with update_position (status CLOSED) is usually what the user wants; confirm before deleting.

delete_position

Permanently delete one screened resume, its file and its analysis. Candidates already invited from it keep their sessions. Cannot be undone.

delete_resume

Permanently delete an upload batch and every resume in it, with their files and analyses. Cannot be undone.

delete_resume_batch

Permanently delete every resume screened for a position; returns how many were deleted. The position itself and any invited candidates stay. Cannot be undone.

delete_resumes_for_position

Disconnects one sheet: Hireinator stops reading and updating it. The customer's spreadsheet and its data are left as they are. Reconnecting needs the browser; confirm with the user first.

delete_sheet_control

Forgets the company's connected Google account and pauses every sheet that used it. Reconnecting needs the browser sign-in; confirm with the user first.

disconnect_google_sheets

Disconnects the company's Workday tenant: new Workday assessment requests stop arriving and results stop being written back. Reconnecting needs the credentials again in the browser; confirm with the user first.

disconnect_workday

Replaces the body of a candidate note. Only its author (or a company admin) may edit it; nobody is emailed. The id comes from list_candidate_notes.

edit_candidate_note

Finds candidates of the company by name or email (ONE person per call: for several people call it once per name; any part, e.g. "priya", "nair priya" or "@acme.com"), archived ones included, and returns each person with every test session (status, score, decision, archivedAt) and every journey (position, stage, status). People with a live (not archived) session or journey come first. sameNameCount is how many OTHER people share the exact name, archived ones included; archived look-alikes rarely need a question. When the conversation already says which one (the position being discussed, the test), use that and say which you picked; otherwise ask, naming their emails and positions. An empty list means nobody of that name has been invited; say so plainly.

find_candidates

Drafts up to 8 AI interview questions from a position's job description, each with a secret rubric, an optional clarification, an answer limit and whether a follow-up is asked. Creates nothing: show the draft to the user, then pass it to create_challenge with challengeType INTERVIEW once they have reviewed every rubric. Costs an AI call, never credits. Emails nobody.

generate_interview_questions

Get one AI grading check: status (PENDING, RUNNING, COMPLETED, FAILED), AI score, sub-scores, reasoning, feedback and suggestions. Use it to follow a check started with run_ai_grading. Cheating risk, indicators and the take-home ownership verdict are signals for a person to review, not a verdict.

get_ai_check

Returns one assessment with its description, duration, status and its challenges in order (type, time limit, take-home effort). Use get_challenge for a challenge's full content.

get_assessment

How many credits one candidate starting this assessment will spend (0 for an MCQ-only test), with the breakdown by question type. Inviting is free; these credits are used when the candidate starts, and it already covers AI grading and the cheating check. Use it before a large invite to check the balance covers it (credits x candidates who start).

get_assessment_credit_cost

Returns the funnel and outcome of each assessment (test) of the company, or of one: invited, not started, in progress, completed, expired (started but ran out of time), completion rate (completed out of those who finished or ran out), graded, average composite score, PASSED and FAILED decisions, pass rate (PASSED out of decided) and average time taken. Use it for "which test has the worst pass rate" or "how is this test doing". Rates are null until there is something to divide; small counts make a rate unreliable, so say how many candidates it rests on. Archived candidates are left out. For one question's difficulty use get_challenge_analytics.

get_assessment_stats

Returns one candidate's journey at a position: current stage, status, sub-state, tags, note count, resume fit score, client feedback and the result of every assessment stage. The id (positionCandidateId) comes from get_position_pipeline or list_candidate_sessions (journey.id). subState is where the candidate is inside the current stage: at an ASSESSMENT stage NONE (no test sent for it yet), INVITED (link sent, not started; inviteExpired true means the link is dead and only resend_candidate_invite helps), IN_PROGRESS, EXPIRED (started, but the time ran out before they submitted), TO_REVIEW (test finished, some answer not graded yet or its AI grade waiting for approval), REVIEWED (every grade decided; stageSession.finalRecommendation says PASSED, FAILED or UNDECIDED); otherResults lists tests the candidate took for this position that no stage names; at SCREEN NOT_SCREENED or SCREENED (a resume fit score exists); at CLIENT_REVIEW the client's answer (AWAITING_CLIENT, CLIENT_INTERESTED, CLIENT_NOT_NOW, CLIENT_PASSED); NONE at every other stage.

get_journey

Get a session's scorecard: decision, composite score and letter grade, averaged sub-scores, and a per-submission breakdown (type, grade status, final and AI score, sub-scores, reasoning). A compact summary; use get_session_results for test results and details. sessionCheatingRisk is the session's integrity signal (the session cheating check, null until one has run); avgCheatingRisk only averages the per-question AI risk. Both are signals for a person to review, not a verdict.

get_candidate_scorecard

Returns one candidate session: status, timing, composite score, the review decision, position, client, journey stage, the per-question submissions (challenge, auto score, AI score, AI grade status, final score), the cheating check and the session behavioral counts. MCQ submissions read aiGradeStatus AUTO_GRADED (scored on submit, no approval needed). The id comes from list_candidate_sessions or a journey's stageSession. Use the results tools for full test output and AI reasoning.

get_candidate_session

Returns one challenge as a recruiter reviews it: the task text, type, difficulty, time limit, the languages offered with their starter code, the public test cases in full, how many hidden test cases there are (their inputs, never their expected outputs), the MCQ questions and options (without which option is correct), the agentic or take-home setup, and an AI interview's questions as the candidate meets them (never the rubric or the resume hints). The answer key is left out on purpose so it never sits in a conversation; use get_challenge_for_edit only when the user is editing the challenge.

get_challenge

Returns how one challenge performs across candidates: attempts, drop-offs, completion rate, average auto score, pass rate at a threshold (default 70), average time and the score distribution in five 20-point buckets. Use it to judge whether a question is too hard or too easy.

get_challenge_analytics

Returns one challenge in full as the team edits it, INCLUDING what candidates must never see: every test case with its expected output, the reference solutions, the MCQ answer key and explanations, the agentic planted defect, the take-home rubric and debrief probes, an AI interview's rubrics and resume hints. Use it only to build the input of update_challenge (or to copy a library challenge's shape for create_challenge); for anything else use get_challenge. Do not repeat answers in the conversation unless the user asks for them.

get_challenge_for_edit

Returns the cached machine translation of a challenge's candidate-facing text into a language, with needsReview and stale flags; null when none exists yet. Candidates who pick that language see it; grading always reads the English.

get_challenge_translation

Returns one agency client in full, including the agency's internal notes and whether candidates are told the client's name (revealToCandidates).

get_client

Returns the company's template hiring process: the ordered stages every new position copies, and whether a PASSED decision moves a candidate to the next stage (passAdvancesStage). Stage kinds: SCREEN (must be first, exactly one), ASSESSMENT (a test; assessmentId omitted means the position's default assessment, at most one stage may rely on that, and an assessment may appear only once), CLIENT_REVIEW (agencies: submitted to the client), INTERVIEW, OFFER, HIRED (must be last).

get_company_hiring_template

Returns the company's credit balance. When it runs out, invited candidates cannot start their test (they see a neutral "unavailable" message), so check it before inviting many people. Hireinator counts usage in credits: one credit is one candidate on a standard test (up to 3 AI-graded coding questions), each agentic round adds 1 credit and each take-home adds 2; MCQ-only tests use none. Credits are used when a candidate starts a test.

get_credit_balance

Returns this month's headline numbers for the company: tests completed, invites expired (links that lapsed unused plus tests that ran out of time; list_needs_attention names the recent ones), median hours from completion to decision, and credits used (candidate starts, screening, parsing, integrations).

get_dashboard_stats

Shows how far one bulk AI grading run has got: total, done, running, queued and failed checks, and per session its grading state and progress over the AI-graded rounds. The batch id comes from grade_candidates_with_ai. A batch is finished when queued and running are both 0; a failed check is retried by grading that candidate again.

get_grading_batch