List jobs from Ashby with their IDs, titles, department, location, and status.

Use this to discover what positions exist before looking at candidates. Returns a paginated list — pass the next_cursor value to fetch more results.

Response: items[] (id, title, status, locationId, departmentId), has_more, next_cursor.

Get full details for a specific job including its description and interview plan stages.

Use this after ashby_list_jobs to understand a position's requirements and hiring pipeline. Fetches the job, resolves the job posting description, and interview plan stages automatically.

Response: job (id, title, status, description, hiringTeam, customFields, locationId, departmentId), interview_stages[] (id, title, type, order).

Get a pipeline summary showing candidate counts per interview stage, per job.

Use this to answer "What does our pipeline look like?", "How many candidates at each stage?", or "Give me an overview of where things stand across open roles." The MCP server fetches and aggregates all applications internally — no need to paginate manually.

Response: jobs[] (job_id, job_title, total_active, total_archived, stages[] (stage_title, stage_type, count)), totals (active, archived, leads).

Get a comprehensive candidate profile.

Returns everything needed to evaluate a candidate: name, contact info, social links, tags, resume/file handles, source, and all their applications with current stages. Fetches the candidate profile, then resolves each application for full details.

Response: candidate (id, name, email, phone, socialLinks, tags, source, profileUrl, fileHandles), applications[] (id, status, job, current_stage, source, hiringTeam).

List all notes on a candidate.

Use this to see existing evaluation notes or comments left by the hiring team.

Response: notes[] (id, content, createdAt, author).

Search for candidates by name or email.

Use this when you know a candidate's name or email but not their ID. Both name and email use AND logic if both provided. Max 100 results.

Response: candidates[] (id, name, email, phone).

Add an evaluation note to a candidate.

Use this to record your assessment or recommendations. The note will be visible to the hiring team in Ashby.

Response: note_id, confirmation message.

Tag a candidate with a label (e.g. "Strong Hire", "Needs Review").

Use this to categorize candidates during evaluation. You need the tag ID from Ashby admin settings.

Response: confirmation message.

Create a new candidate and add them as a lead on a job.

Use this to source candidates (e.g. from LinkedIn) directly into Ashby. Creates the candidate, adds a Lead application on the specified job, and optionally attaches a note with sourcing context.

Response: candidate_id, application_id, note_id (if note provided), confirmation message.

Download and read a candidate's resume or uploaded file.

Use this after ashby_get_candidate to read the actual content of a resume or file. Takes a file handle string from the candidate's fileHandles array. Fetches the file URL from Ashby, downloads the file, and returns the text content.

Supports PDF, DOCX (as plain text), and plain text files. For other formats, returns the download URL.

Response: filename, content (extracted text), or url (for unsupported formats).

List all candidates/applications for a specific job.

Returns each application with the candidate's name, current interview stage, and status. Use this to see the pipeline for a job. Pass next_cursor to paginate.

Response: items[] (application_id, candidate_id, candidate_name, status, current_stage, source, createdAt), has_more, next_cursor.

Get full application details including stage history, hiring team, feedback, and criteria evaluations.

Use this to deep-dive into a specific application. Fires four API calls concurrently for speed.

Response: application (id, status, candidate, job, current_stage, hiringTeam, source, customFields), stage_history[], criteria_evaluations[], feedback[].

Get a candidate's submitted application form responses for a specific application.

Use this to read what a candidate actually wrote in their application — their answers to screening questions, cover letter text, and any other form fields. Use after ashby_list_candidates_for_job or ashby_get_application_details when you need to evaluate a candidate's application content.

Response: application_id, candidate_name, job_title, form_responses[] (question, field_type, answer).

List applications across all jobs with date, status, stage, and source filters.

Use this to answer operational questions like "How many people applied this week?", "Show me all candidates in Application Review", or "Who applied via the Chrome extension?" Date and status filtering happens server-side for efficiency. Stage and source filters are applied by the MCP server.

Response: items[] (application_id, candidate_id, candidate_name, candidate_email, status, current_stage, source, job_id, job_title, createdAt), has_more, next_cursor.

Archive an application with an optional reason and rejection email.

Workflow: call ashby_list_archive_reasons to pick a reason, then ashby_list_email_templates to pick an email template, then call this tool. Automatically resolves the correct "Archived" interview stage for the application's job.

Response: application_id, status, archive_reason_id, email_sent, message.

Archive multiple applications at once with an optional reason and rejection email.

Accepts up to 25 application IDs. Uses the same archiving logic as ashby_archive_application for each one. Caches interview plan lookups for efficiency when applications share the same job.

Response: total, succeeded, failed, results[] (application_id, success, error?).

List all interview stages across all interview plans.

Use this to understand the hiring pipeline and get stage IDs for ashby_move_application_stage. Fetches all interview plans, then resolves stages for each.

Response: plans[] (plan_id, plan_title, stages[] (id, title, type, order)).

List upcoming and pending interview schedules.

Use this to answer "What interviews do I have this week?", "Who needs to be scheduled?", or "Show me all upcoming interviews." Fetches interview schedules from Ashby, resolves candidate and job details, and filters by date range.

Response: items[] (schedule_id, status, candidate_name, candidate_id, job_title, job_id, interview_stage, events[] (start_time, end_time, interviewers, meeting_link, location, has_submitted_feedback)).

Move an application to a different interview stage.

Use this to advance a candidate through the pipeline. Get stage IDs from ashby_list_interview_stages. Moving to an "Archived" type stage requires an archive reason — use only for active transitions.

Response: updated application with new current_stage.

Get submitted feedback/scorecards for an application.

Use this to review interviewer evaluations and scores.

Response: feedback[] (form definition with sections/fields, submitted values).

List available archive/rejection reasons.

Use this as the first step when archiving a candidate. Returns reasons you can pass to ashby_archive_application. Requires the "hiringProcessMetadataRead" API key permission.

Response: reasons[] (id, text, reasonType).

List available email templates for rejection/archive emails.

Use this to find the template ID to pass to ashby_archive_application when sending a rejection email. Requires the "hiringProcessMetadataRead" API key permission.

Response: templates[] (id, name, and any other fields returned by the API).

Call any Ashby API endpoint directly. Escape hatch for endpoints the narrow ashby_* tools don't wrap (e.g. offer.list, user.list, department.list, interviewPlan.list, candidate.update).

Prefer the dedicated tool when one exists — they return cleaner, summarised data. Use this when you need an endpoint that has no dedicated tool.

Call ashby_get_api_docs first if you're not sure which endpoint to use.

Handles auth, retries, and timeouts automatically. Returns the raw Ashby response including success, results, moreDataAvailable, nextCursor, and any error details — nothing is stripped.

Return a reference for the Ashby API: base URL, auth, response envelope, pagination, and a curated endpoint index with parameter hints and common gotchas.

Call this before ashby_call_api when you're unsure which endpoint or param names to use. The full official reference is at https://developers.ashbyhq.com/reference/.