Ashby

Add a note to a candidate's profile.

add_note_to_candidate

Move an application to a different interview stage. The \`stageId\` must be a stage in the application's own interview plan. Call \`get_interview_plan\` with the applicationId first to list the plan's stages and their IDs, then pass the target stage's ID here. Before you move the application, always tell the user the names of the stages it is moving from and to. Archiving also cancels the application's upcoming interviews that have no submitted feedback. Depending on how those interviews were scheduled, interviewers and the candidate may be notified through their calendar invites. Pass \`cancelScheduledInterviews: false\` if the user wants to keep them.

change_application_stage

Create a new application for a candidate on a specific job. Optionally provide an \`interviewStageId\` to place the application at a specific stage. Call \`get_interview_plan\` with the jobId first to discover available stage IDs. If omitted, the application starts at the first stage.

consider_candidate_for_job

Create a new candidate record in Ashby with a name and optional contact information.

create_candidate

Look up filterable fields for a given object type. Returns field paths, valid operators, and selectable values. Use this before calling \`filter_records\` when you do not already know the correct field path. **Always pass a searchTerm** with 2-3 short, specific keywords for the fields you need (for example \`"offer status"\` or \`"hire date salary"\`). Results are ranked by relevance. Use the returned field paths exactly as shown when constructing filters. Field paths are opaque API identifiers: if a path contains dots, the final segment is not valid by itself. For example, use \`feedback_form.overall_recommendation\`, not \`overall_recommendation\`. ## Search guidance - Use field discovery only when you do not already know the next field to try. - Search for the single next missing field, not for reassurance or alternate formulations. - If you already have one direct field for the current step, try using it before searching for additional alternatives. - Avoid broad keyword combinations when a narrower search can answer the next step.

describe_object_fields

Filter records of a given object type using a structured JSON filter. Supports result modes: "ids" (default), "count" (total count only), "summary" (IDs plus basic entity details). The `filter` argument must always be a JSON-serialized object. Filters are capped at max depth 3, 8 predicates, 5 child filters per and/or group, and 2 sort fields. Use this tool after identifying the correct object type and field paths. For structured criteria, first call `describe_object_fields` unless you already have the exact field path from a prior tool result. Do not invent common field names such as `title`, `name`, `application_id`, or `overall_recommendation` unless that exact field path was returned for the selected object type. Use the value form that matches the field and tool behavior: - **Field paths**: Use the complete field path returned by `describe_object_fields`, including prefixes such as `feedback_form.`, `candidate.`, or `interview.`. Never shorten a returned field path to only the final segment. - **Label-based selectable fields**: For fields such as tags, statuses, users, teams, and similar selectable values, use the human-readable label where supported. The system automatically resolves labels to IDs for supported fields. - **Reference fields**: For many reference fields, including many fields named like `*_id`, the system may support either: - a resolved ID, or - a human-readable title/label. - **Prefer IDs when available**: If you already resolved the referenced entity and have its ID, prefer using the ID for reliability and disambiguation. - **Score fields**: Fields whose `Value type` is Score require numeric values: 4 = Strong Yes, 3 = Yes, 2 = No, 1 = Strong No, 0 = No score provided. Do not pass labels like "Strong Yes" to Score fields. - **Literal fields**: For normal string, number, boolean, or date fields, use the literal value in the appropriate format. - Follow the chosen field's `Value type` line from `describe_object_fields`. Do not infer the value form from the field name alone. - **Filter errors**: If an error says "Did you mean", retry once with one of the suggested complete field paths before changing tools or object types. ## Expensive queries - Text matching on \`resume_full_text\` across all candidates, and org-wide counts with no job, stage, or date scope, can be too slow to run. Add a selective filter alongside them. - If a call fails because the query was too expensive, do not repeat the same filter. Narrow it, or tell the user the request is too broad. ## Sorting Use `sort` with field paths from `describe_object_fields` for latest, earliest, highest, lowest, or alphabetical requests. ## Filter format examples Every filter is one object with a top-level \`"operator"\` — put the operator in the \`"operator"\` key, never as a key nested under the field. - Field operators — \`{ "operator": "<op>", "field": "<field_path>", "value": <value> }\`: - "equals": \`{ "operator": "equals", "field": "status", "value": "Active" }\` - "similarTo" (fuzzy text match — the default for free-text like names, schools, companies; tolerates typos): \`{ "operator": "similarTo", "field": "name", "value": "john" }\` - "contains" / "starts" / "ends" (literal string matching; use "contains" only when the user explicitly asks for exact substring containment): \`{ "operator": "contains", "field": "name", "value": "john" }\` - "greater" / "less" / "greaterOrEqual" / "lessOrEqual" (numbers only): \`{ "operator": "greaterOrEqual", "field": "years_of_experience", "value": 2 }\` - "empty" (no value): \`{ "operator": "empty", "field": "primary_personal_email_address" }\` - "daterange": \`{ "operator": "daterange", "field": "created_at", "value": { ... } }\` — see **Date range filters** below. - Logical operators: - \`{ "operator": "and", "filters": [<filter>, ...] }\` - \`{ "operator": "or", "filters": [<filter>, ...] }\` - \`{ "operator": "not", "filter": <filter> }\` Do not nest the operator under the field: \`{ "name": { "contains": "peter" } }\` is wrong. Always use the flat operator/field/value shape shown above. **Example**: Find active applications for a job: ```json { "operator": "and", "filters": [ { "operator": "equals", "field": "job_id", "value": "<job_id>" }, { "operator": "equals", "field": "status", "value": "Active" } ] } ``` **Date range filters** — for \`"operator": "daterange"\`, \`value\` is one of these shapes (dates are \`YYYY-MM-DD\` strings; never epoch/ISO timestamps, and not keys like \`from\`/\`to\`/\`gte\`/\`after\`): - \`{ "type": "Since", "date": "YYYY-MM-DD" }\` — on or after the date - \`{ "type": "Before", "date": "YYYY-MM-DD" }\` — before the date - \`{ "type": "On", "date": "YYYY-MM-DD" }\` — exactly on the date - \`{ "type": "Between", "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" }\` — absolute window - \`{ "type": "Previous", "unit": "1 DAY"|"1 WEEK"|"1 MONTH"|"3 MONTH"|"1 YEAR" }\` — rolling window ending now **Example**: Applications created within an explicit date window: \`\`\`json { "operator": "daterange", "field": "submitted_at", "value": { "type": "Between", "start": "2026-03-27", "end": "2026-06-25" } } \`\`\` When a request is about the current user, use the value "@me" on the relevant user field. The server resolves "@me" to the authenticated user, so you don't need to know their name or Ashby ID. This works on any user field, such as "involves", "hiring_manager", "recruiter", or other fields whose values are Ashby users. To scope to a different person, pass that user's name as the value instead. **Example**: Find applications where the current user is involved: ```json { "operator": "equals", "field": "involves", "value": "@me" } ```

filter_records

Fetch details about one or more candidates. ## Choosing sections - For a candidate summary, omit the `sections` parameter. - Request only the sections relevant to the user's question. - For questions about whether a candidate mentioned, shared, or said something, start with `emails` and `interviewFeedback`, then fetch other relevant communication/context sections before saying the information was not found. - For all interview feedback visible to the current user, pass `sections: ["interviewFeedback"]`. Use `get_submitted_feedback` when the user specifically asks for their own feedback. ## Application scoping When applicationIds is not provided, this tool returns data based on the candidate's most recent applications, prioritizing non-archived applications. For role-specific questions, call `filter_records` with `objectType: "application"` filtered to the candidate, then retry with the relevant applicationIds. ## Source and credited-to Basic candidate info reports the candidate's own source and credited-to in `<CandidateAttribution>`. These are candidate-level values; do not report them as application-level attribution. ## Interview transcripts The `interviewTranscripts` section returns metadata only (transcript ID, interview title, timestamp, interviewers) without the full transcript text. To read the full transcript, call `get_record_details` with `entityType: "transcript"` and `entityIds` containing the transcript ID from the `identifier` attribute. ## Pagination Each section returns metadata indicating if more items are available. Use offset and limit to paginate: - offset: Number of items to skip (default: 0) - limit: Maximum items to return per section (default: 5, maximum: 10)

get_candidate

Get a detailed interview briefing for a specific Ashby interview event. Use this when the user asks for briefing context for an upcoming or pending interview, such as who is interviewing, candidate background, resume summary, candidate/job custom fields, candidate source, or interview instructions. The required \`interviewEventId\` comes from \`list_interviews\`, \`get_pending_tasks\`, or the \`interviewEventId\` field returned by \`get_record_details\` for an interview record. Set \`includeInstructions\` to true only when the user needs interview instructions. The response is read-only briefing data and includes candidate/job context, hiring team members, co-interviewers, resume summary, custom fields, and links back to Ashby.

get_interview_details

Get the interview plan and its stages for an Ashby application or job. Provide either an applicationId or a jobId (at least one is required). If applicationId is provided, returns the interview plan for that specific application. If jobId is provided, returns the default interview plan for that job

get_interview_plan

Get pipeline metrics for one or more Ashby jobs, including per-stage application counts. Use this when the user asks how many candidates or applications are in a job's pipeline, how candidates are distributed across interview stages, or for a pipeline overview. First resolve job IDs with \`search_records_by_name\` for a simple job-name lookup or \`filter_records\` for structured criteria, then pass those IDs here. Batch multiple job IDs in one call when comparing pipelines. The response groups jobs that share an interview plan and returns job summaries, interview plan stages, and per-job counts for each stage. Use \`get_interview_plan\` instead when the user needs the stage structure without counts.

get_job_pipeline