The Interview-Setup Skill

---
name: intervyo-interview-setup
description: "Turn a plain-language hiring, admissions, training, or certification brief into a structured intervyo.ai assessment via the Intervyo MCP tools. Use WHENEVER the user wants to set up, build, or extend an interview, assessment, screening pipeline, rounds/stages, AI interviewer, or scorecard on intervyo — even if they only describe the role in words and don't name the tools. Claude proposes the rounds, timing, and evaluation dimensions as defaults; the user picks rounds and tunes scoring. Enforces a plan-then-confirm flow since the create tools mutate the workspace."
---

# Intervyo Interview Setup

Convert a hiring/assessment brief into a working intervyo.ai setup. Your job is to
map plain language onto four entities and create them in the right order with the
right field values.

## Mental model (use these words with the user; map to tools internally)

- **INTERVIEWER** — the AI persona + scorecard that *runs* a Round. **No separate
  create step**: it's defined **inline in `create_round`** via a nested
  `interviewer` object (create + link are atomic). `update_round` edits it with the
  same object; `get_round` returns it. (No `create_interviewer`/`list_interviewers`
  tool.)
- **AI AVATAR** — the voice identity (name + gender + voice + **language**) an
  Interviewer uses in a live session. There is no reference image or talking-head
  video — an avatar is just a voice. The interview **language lives on the avatar**,
  so choosing the avatar also picks the language the interview is conducted in.
  Tool: `list_ai_avatars` (read) / `create_ai_avatar`. You attach one to an
  Interviewer with `ai_avatar_id`. **Always `list_ai_avatars` FIRST and let the user
  choose which avatar to use before you create the Interviewer** — the Interviewer's
  voice/gender/language all come from it. **Reuse by default: pick an existing
  avatar. Only `create_ai_avatar` when the user explicitly asks for a new one** — a
  created avatar is `ready` immediately (name, gender, voice, language; no image
  upload, no generation step).
- **ROLE** — what we're hiring/assessing for: the job description, the skills, the
  pass bar. Tool: `create_role`. ID: `role_id`.
- **ROUND** — one step of a Role's interview (screen, technical, final), each with
  its own pass threshold and automation. Tool: `create_round`. ID: `round_id`.
- **SESSION** — a scheduled interview that invites one candidate to a Role's Round.
  Tool: `create_session`. Auto-emails the candidate and returns a `join_url`.

Rule of thumb: **A Role has Rounds; each Round is run by an Interviewer; a Session
invites a Participant to take the Role.**

## The entity chain (this is why build order matters)

A Round (`create_round`) needs a `role_id` and a full `interviewer` object (the
interviewer is created inline with the round). The Role must exist first:

```
0. AI Avatars    (list_ai_avatars)            → list FIRST and have the USER pick the avatar (sets the interviewer's voice/gender/language); create_ai_avatar only if the user explicitly asks
1. Role          (create_role)                → capture the role_id
2. Rounds        (create_round)               → pass role_id + a nested `interviewer` object; creates the interviewer AND round atomically
3. Participants  (create_participant, …)      → only when adding candidates
4. Sessions      (create_session)             → schedules the interview, sends invite
```

Building out of order (a Round before its Role) means the Round has nothing to point at and the call fails.

Step 0 is not optional housekeeping: because the interviewer's voice, gender, and
**language** are inherited from its avatar, you must `list_ai_avatars` and have the
**user choose an avatar before** you call `create_round` (its `interviewer.aiAvatarId`
comes from that list). To run a new round on an EXISTING interviewer, pass
`interviewer_id` instead of the nested object.

## Core principle: you suggest, the user chooses

The user should never have to design the assessment from a blank page. **Always
propose a complete, opinionated default** — the rounds, the timing for each, and the
evaluation dimensions for each Interviewer — derived from the role and seniority.
Then make clear that these are *your suggestions* and the user decides what they
actually want. The user picks which rounds to keep, adjusts timings, and approves or
edits the evaluation dimensions before anything is built. Do not silently impose the
defaults, and do not make the user invent the structure themselves.

So: the **role identity** (title, seniority, must-have skills), **company/client name**, and **desired number of interview rounds** should come from the user when possible. Always ask how many rounds are needed. If the user is unsure, recommend a sensible default based on the role and seniority, then let the user approve or adjust it. The **duration of each round and the scoring dimensions are things you propose** — never things you demand the user specify up front.

## Required workflow — do not skip

**A. Clarify only the role identity, company identity, persona name, role name, round count, and round names — and only if missing.** Ask 1–5 questions ONLY
when you can't infer them: role title, seniority, must-have skills, **company/client name**, **the Role name** (the `template_name` shown in dashboards — propose a sensible default like "<Job Title> - <Location>" and let the user confirm or rename), and **how many interview rounds are needed**. **Always ask for the company name before creating or updating an Interviewer, Role, or Round when it is missing**, because the persona and interview context must mention the correct company/client. **Always ask how many rounds of interview are needed before planning or creating rounds**; if the user is unsure, propose a default round count based on role seniority and explain that they can approve or change it.

**Round naming rule:** if the user chose **exactly 1 round, do NOT ask for a round name — automatically use `stage_name: "Screening"`**. If the user chose **2 or more rounds, ask the user to name each round** (offer sensible defaults like "Screening", "Technical Deep-Dive", "Final Managerial" that they can keep or rename).

**Do NOT ask the user how long each round should be or what to score on** — propose timings and evaluation dimensions yourself in step B. If the brief already names a round count, round names, or timing, treat them as constraints and build your suggestion around them.

Also, when setting up the Role, **ask the user for the job description text**. The
JD is text, not a file — there is nothing to upload. Put the full JD as plain text
in the Role's `description`, and a clean Markdown version in
`knowledge_base_extracted` (see "The JD is text" below). Ask once, and proceed with
whatever the user gives you — never block the build waiting on a JD.

**B. Preflight: list/get to validate state before you plan.** Never assume the
workspace is empty or that an entity exists — check first (see "Validate first"
below). Concretely: `list_ai_avatars` to pick the voice, `list_roles` to see whether
a matching Role already exists, and — if extending an existing Role — `get_role`
plus `list_rounds` (filtered by `role_id`) to read what's already there (each round's
interviewer comes back with it). Fold the findings into the plan ("the Role *X*
already has 2 rounds, so I'll add round 2 at `stage_order` 2").

**C. Present a SUGGESTED PLAN the user can edit, before creating anything.** The
create tools mutate the workspace, so the user sees and shapes the whole thing
first. Show your recommended defaults clearly as *suggestions*:

- **Rounds (suggested)** in order: name → Interviewer → suggested duration → pass
  mark → automation rule. Use the round names from step A (a single round is
  always named "Screening" automatically; multi-round names come from the user).
  Include the user's requested round count when provided.
  If the user did not know the count, show your recommended count and why. State
  plainly that the user can drop, add, reorder, or re-time any round.
  **Duration guidance:** a round with `coding_enabled: true` should be **around
  50 minutes**; any other interview round should be a **minimum of 40 minutes**
  (phone-screening rounds are the exception and stay short).
- **Evaluation dimensions (suggested)** for each Interviewer — the 3–5 dimensions
  with weights summing to 100 — and invite the user to adjust the dimensions and
  weights. (If they change weights, re-balance so the total stays 100.)
- The Role: `template_name`, `description` (the JD text) + `knowledge_base_extracted` (JD markdown), key skills, `use_case`.
- Interviewers to **reuse vs create** (based on the preflight check).

Make the choices easy: tell the user something like "here's what I'd recommend —
keep all of it, or tell me which rounds you want and how you'd tune the scoring."

**D. Let the user choose, then confirm.** Apply their selections — the rounds they
kept, the timings and dimensions they tuned — and only call create tools once they
approve the adjusted plan. Never create before the user has chosen.

**E. Execute in chain order** (Interviewers → Role → Rounds), using the *chosen*
values, capturing each id as you go and feeding it into the next call. Reuse the
ids the preflight found instead of creating duplicates.

**F. Report what you built**: a short summary, the Role's `role_id`, and the
realistic next step (see "After the build").

## Validate first: list/get before you create

Creating blind is where these setups break — you get duplicate Interviewers,
duplicate Roles, colliding `stage_order`, or a Round pointing at an id that doesn't
exist. Read the current state before every create. The list/get tools are
non-mutating and safe to call freely.

- **Before a Round's interviewer** — first `list_ai_avatars` and have the **user
  choose the avatar** (see the next bullet); the interviewer can't be built correctly
  until its voice/gender/language source is settled. Build **narrow, single-purpose**
  interviewers (e.g. "ITOM Specialist", "Friendly Screener"), not one giant
  do-everything expert — each round gets the interviewer that fits it. (To run a new
  round on an interviewer another round already uses, pass that round's
  `interviewer_id` instead of a fresh `interviewer` object.)
- **Before assigning an avatar** — call `list_ai_avatars` FIRST and present the
  options so the **user chooses which avatar to use before the Interviewer is
  created**. The chosen avatar sets the interview's voice, gender, and **language**,
  so this is a real decision, not a default — don't pick silently. `ai_avatar_id`
  must be one returned by that list; never invent an id, and match the avatar's
  gender/voice/language to the persona so voice, pronouns, and language stay
  consistent (an avatar is a name + gender + voice + language — no image).
  **Reuse, don't create: always assign an existing avatar. Call `create_ai_avatar`
  ONLY when the user explicitly requests a new one** — never create one on your own
  to "complete" the persona. If none fit and the user hasn't asked for a new one,
  ask the user how to proceed rather than creating one or leaving the interviewer
  without a language.
- **Before a Role** — call `list_roles`. If a Role with the same intent already
  exists, ask whether to extend it rather than create a near-duplicate. Role names
  must be unique — `create_role` returns 409 on conflict.
- **Before a Round** — call `list_rounds` filtered by `role_id` to see existing
  rounds. Use it to pick the next free `stage_order` (don't collide or reuse 0),
  avoid duplicate rounds, and keep thresholds rising relative to what's already
  there.
- **Before referencing any id you didn't just create** — if the user names an
  existing Role/Round, `get_*` it (`get_role`, `get_round`) to confirm it resolves
  and to read its real fields (a round's interviewer comes back with `get_round`),
  rather than guessing the id or its config.
- **When extending an existing setup** — always `get_role` + `list_rounds` first,
  so the plan reflects what's actually there and new rounds slot in at the correct
  order with sensible thresholds.

If a referenced entity does **not** exist, say so and offer to create it — don't
fabricate an id or silently proceed.

## Field decisions that matter

The tool schemas carry the full field list; these are the choices that are easy to
get wrong.

### Casing gotcha — round fields snake_case, the interviewer object camelCase
On `create_round` / `update_round` the **round fields are snake_case**
(`role_id`, `stage_order`, `pass_threshold`, `duration_minutes`, `stage_type`),
but the **nested `interviewer` object is camelCase** (`name`, `persona`, `useCase`,
`evaluationDimensions`, `additionalInstructions`, `voiceGender`, `aiAvatarId`, plus
`context`/`interaction` sub-objects) — it mirrors the REST `interviewer` contract.
So: snake_case around it, camelCase inside `interviewer`. Getting the inner object
snake_case is the most common cause of a silent validation failure.

### The interviewer object — required fields
Inside `create_round`'s `interviewer`: `name`, `persona` (how the AI introduces
itself at the start of a session), `evaluationDimensions`, and
`additionalInstructions`. Skipping `persona` is a common miss — write a 1–2 sentence
in-character opener. `useCase` defaults to `hiring`.

**Persona must be under 200 characters, simple, and company-specific.** Give the persona a real simple **name** (e.g. *Riya*, *Aman*), **infer gender from that name**, and keep it consistent across voice, pronouns, and avatar gender. The `persona` field must be a short first-person opening line only, using this format:  
`I am Riya, recruiter from <Company Name>. I will conduct your <Role/Skill Area> interview today.`  

Examples (each is one short first-person line, under 200 characters):
- `Hi, I am Riya from <Company Name>. I'll be conducting your interview today for the <Role> role.`
- `Hi, I'm Aman from <Company Name>. I'll be taking your <Skill Area> interview today.`
- `Hello, I am Neha from <Company Name>. I'll be your interviewer today for the <Role> position.`
- `Hi, I'm Karan from <Company Name>. I'll be running your technical round for the <Role> role today.`

Keep it below **200 characters**. Avoid complicated names, long backstories, heavy titles, third-person bios, or verbose character descriptions. If the company name is missing, ask for it before creating or updating the persona. Give the interviewer a voice with
`ai_avatar_id` from `list_ai_avatars` — list these and let the user pick **before**
creating the interviewer (reuse an existing avatar; an avatar is a name + gender +
voice + **language**, with no image or video, and its language is the language the
interview is conducted in).

### Weights must sum to exactly 100
`evaluationDimensions` takes 3–5 dimensions, each `{name, description, weight}`,
and the weights MUST total **100**. Each dimension should trace back to a specific
JD requirement — don't pad with generic defaults. Always write concrete
`additionalInstructions` (the single AI-instruction field for the round) and fill
`context` — an object `{organizationContext?, domainContext?}` — the live AI
interviewer reads these directly. Optionally tune `interaction` (`tone`, `style`,
`difficulty`, `probingDepth`). **Score scale is not set here — new interviewers
default to a 0–10 scale.**

### AI instruction must force separate evaluation-dimension feedback
There is now a **single** AI-instruction field per round: the interviewer's
`additionalInstructions` (inside `create_round`'s `interviewer` object). It must
explicitly tell the AI to produce a separate evaluation breakdown for **each
configured evaluation dimension**. Do not rely only on `includeScoreBreakdown: true`.

Add this instruction block to every round's `interviewer.additionalInstructions` unless the user explicitly asks for a different report format:

```text
Evaluation reporting rules:
- Always evaluate and display every configured evaluation dimension separately.
- For each dimension, provide: dimension name, score, evidence from the candidate's answers, strengths, gaps, and improvement feedback.
- Do not collapse the report into only one Overall score.
- Do not reuse the same generic AI feedback across multiple dimensions.
- Keep Overall AI Feedback separate from dimension-level feedback.
- If there is not enough evidence for a dimension, state "Insufficient evidence" for that dimension and explain what was missing.
- Final recommendation must be based on the weighted average of all evaluation dimensions.
```


### There are TWO different difficulty fields — don't mix them up
- **Interviewer** persona — `interaction.difficulty`: `easy | medium | hard | adaptive`.
- **Round** — `difficulty`: `beginner | intermediate | advanced | expert | adaptive`.

Use the stage enum on Rounds and the interaction enum on Interviewers.

### Role required fields
`template_name`, `use_case`, and `description` (the full job description as plain
text — the JD itself, not a one-line summary). `description` is required and often
forgotten. Pair it with `knowledge_base_extracted` — the same JD as clean Markdown,
which is what reviewers read in "View JD". `success_outcome` is auto-derived from
`use_case` if omitted but is safer to set explicitly. Useful optional fields:
`domain`, `level`, `skills`, `soft_skills`, `default_difficulty`,
`default_session_mode`, `visibility`. (`objective`, `requirements`, and
`additional_notes` are no longer accepted — they're folded into the JD. Duration is
set per Round via
`create_round`, not on the Role.)

### Rising pass thresholds
`pass_threshold` is 0–100 and should **rise across rounds** (e.g. 60 → 70 → 75 →
80): a screen is a low bar, a final round is a high one.

### Automation rule per round
`automation_rule`: **`none | auto_advance_if_passed | require_reviewer_approval | auto_reject_if_failed | auto_assign_next_stage`** (default
`none`). Use `auto_advance_if_passed` for early rounds; put `require_reviewer_approval`
**before a final or high-stakes round** so a human signs off. Use
`auto_reject_if_failed` to drop candidates who miss the bar automatically.

### Round `type` vs `stage_type`
- `type` (required) is a **free-form label** like `"screen"`, `"technical"`,
  `"final"` — it's used in reports/UI. Do **not** pass `"ai_interview"` here unless
  that's literally the label you want shown to candidates.
- `stage_type` is the interview-format enum: `ai_interview | roleplay_simulation |
  practice_session | manual_review | async_assessment | final_review`. This is
  what picks the session mode.

Set `stage_order` starting at **0**, give each Round a sensible `duration_minutes`
(≈30 screen, 45 standard, 60 deep-dive), and set `allow_retake: true` on training
rounds where retries help.

### `use_case` and `success_outcome` must match intent
`use_case`: `hiring | admissions | training | custom_api` — set it on both the
Interviewer and the Role (snake_case `use_case` on both MCP tools). Pick the
Role's `success_outcome` to match:

- hiring → `hire_no_hire`
- admissions → `admit_reject`
- training → `ready_needs_training`
- certification → `certified_not_certified`
- generic → `pass_fail`
- anything else → `custom`

### Attachments: ask for Drive public URLs (JD + resumes)
The setup runs better when the source documents are attached, so **prompt the user
for a public Google Drive URL** at the two points where a document matters:

- **Participant / resume** — when adding a candidate, ask for a public Drive link
  to their resume and pass it as `resume_url` on `create_participant` /
  `bulk_create_participants`. A `resume_url` triggers auto skill/language
  extraction, so it's strictly better than creating the participant bare. (If the
  user instead hands you the actual PDF file, use `create_participant_with_resume`
  with `resume_filename` + `resume_base64` — same outcome, different input.)

In both cases the link must be **publicly accessible** (or at least readable by
the Intervyo account) — a restricted Drive link won't parse. Tell the user to set
sharing to "anyone with the link" if a fetch fails. Always ask, but treat the link
as optional: proceed without it rather than blocking the build, and never
fabricate a URL.

For PDFs the user hands you as raw bytes, the canonical flow is `upload_file`
(`{filename, content_base64, purpose: "resume" | "knowledge_base"}`) → returns a
`{url}` → use that `url` as `resume_url` or in `knowledge_base_links`. Keep files
under ~10 MB (base64 inflates the request ~33%).

### The JD is text (no file, no upload)

The job description lives on the Role as text — there is no PDF to generate and
nothing to upload. When you create or update a Role, set both:

1. **`description`** — the full JD as plain text, verbatim (same sections, same
   bullets, no rewording). This is the raw JD stored on the Role.
2. **`knowledge_base_extracted`** — the same JD as clean GitHub-flavored Markdown:
   `##` section headings (typically Overview, Responsibilities, Requirements, Nice
   to have, Compensation & benefits), `-` bullet lists, short paragraphs otherwise.
   **No top-level `# Title`** (the Role already has a name). Reorganize and tidy the
   JD — **never invent** responsibilities or requirements not in the source. This is
   what reviewers read in the "View JD" dialog.

A Role grounded in the actual JD interviews better, so always pass the JD when you
have it. (`knowledge_base_links` still exists for genuinely separate reference URLs,
but it is **not** where the JD goes.)

### Destructive tools
`delete_*` tools require `confirm: true` and cascade. Never call them unless the
user explicitly asks to delete.

## After the build (how candidates actually get invited)

The Role itself doesn't invite candidates — a **Session** does. Once the Role and
Rounds exist, the realistic next steps are:

- **Add candidates** with `create_participant`, `create_participant_with_resume`
  (PDF in one call), or `bulk_create_participants` (each row can carry a `role_id`
  and a `resume_url` for auto skill-extraction). Ask the user for a public Drive
  URL of each candidate's resume and pass it as `resume_url`; if they give you the
  PDF itself, use `create_participant_with_resume` instead. The resume is optional
  — add candidates without it if unavailable.
- **Schedule the interview** with `create_session`: required fields are
  `candidate_id`, `role_id`, and `stage` (the round label, e.g. `"screen"`). The
  invite email goes out automatically; the response includes a `join_url`. Pass an
  `idempotency_key` so retries don't double-send. Use `scheduled_at` + `timezone`
  if the user wants a specific time; otherwise the candidate gets the link to take
  it whenever.
- **Get results** by either polling `get_session` until `status` is `completed`,
  or by listening for the `session.completed` webhook event.

Tell the user these options in step F rather than implying the Role has its own
apply link.

## Setting up a single Round + interviewer from a JD (approval-gated)

When the user wants **one round with its interviewer for a specific JD** (rather than
a whole multi-round loop), follow this exact order and **do not call any create or
update tool until the user explicitly approves the spec**. Every choice must trace
back to an actual JD requirement — no generic defaults.

1. **List AI avatars and let the user choose one — do this first.** Call
   `list_ai_avatars`, present the options, and have the **user pick the avatar
   before anything else**. The chosen avatar sets the interview's voice, gender, and
   **language**, so the interviewer can't be specced without it. The `interviewer`
   object must **reuse** a real `aiAvatarId` from this list — do **not** call
   `create_ai_avatar` unless the user explicitly asks for a new avatar.
2. **Check the Role.** `list_roles` (and `get_role` + `list_rounds` if extending an
   existing Role) so the new round slots in at the right `stage_order`. Read-only —
   create or change nothing yet.
3. **Ask for a persona name and company name** (e.g. *Riya from Stellar Consulting*, *Aman from Deloitte*) when either is missing. Infer gender from the name and
   apply it consistently across the persona's voice (avatar gender/voice), pronouns,
   and opening line. Keep the persona under 200 characters, simple, first-person, and company-specific; avoid complex names, third-person bios, or long backstories.
4. **Present the full proposed spec for approval** before creating or changing
   anything:
   - Persona name, inferred gender, and company/client name
   - The user-chosen `aiAvatarId` + its voice, gender, and **language**
   - Simple first-person opening line (`persona`) using the company/client name, under 200 characters
   - `useCase`
   - 3–5 `evaluationDimensions` with weights summing to **exactly 100**
   - Each dimension mapped to a specific JD requirement
   - The round it attaches to: `role_id`, `stage_type`, `stage_order`, `pass_threshold`
5. **Stop and wait** for explicit approval.
6. **Execute the approved spec only after the user confirms** — `create_round` with
   the `interviewer` object inline (or `update_round` with a nested `interviewer` to
   edit an existing round's interviewer), using the valid `aiAvatarId`.

Ground the Role in the JD: put the JD text in the Role's `description` and a clean
Markdown version in `knowledge_base_extracted`. There's no file to upload.

## Worked example (ServiceNow, ITOM + HRSD opening)

**Interviewers** (reuse if present, else create):

| Interviewer | Suggested scoring dimensions (sum = 100, user can retune) |
|---|---|
| Friendly Screener | Communication 40 / Motivation 30 / Basics 30 |
| Platform Fundamentals | Tables & ACLs 40 / Scripting 35 / Integrations 25 |
| ITOM Specialist | Event Mgmt 35 / Discovery & CMDB 40 / Comms 25 |
| HRSD Specialist | Case Mgmt 40 / Employee Center 35 / Knowledge 25 |

**Role:** "ServiceNow Engineer — ITOM + HRSD"  (`use_case: hiring`,
`success_outcome: hire_no_hire`)

**Rounds (suggested — the user keeps, drops, or re-times these):**

| `stage_order` | Round (`type`) | Interviewer | Time | Pass | `automation_rule` |
|---|---|---|---|---|---|
| 0 | screen | Friendly Screener | 20 min | 60 | auto_advance_if_passed |
| 1 | platform | Platform Fundamentals | 45 min | 70 | auto_advance_if_passed |
| 2 | itom | ITOM Specialist | 45 min | 75 | auto_advance_if_passed |
| 3 | hrsd | HRSD Specialist | 45 min | 75 | require_reviewer_approval |

Present this as a recommendation, e.g. "I'd suggest these four rounds — want all
of them, or just the screen plus one deep-dive? And tell me if you'd retune any
of the scoring weights." Then build only what the user selects.

## Why it's built this way

- **Suggest, then let the user choose.** People shouldn't design an assessment
  from a blank page, but they should stay in control. Proposing opinionated
  defaults for rounds, timing, and scoring — then letting the user keep, drop, or
  tune them — gives expert structure without taking the decision away from them.
- **Validate before creating.** Listing/getting current state before every create
  is non-mutating and cheap, and it prevents the most common failures: duplicate
  Interviewers and Roles, colliding `stage_order`, and Rounds that reference an
  id that doesn't exist.
- **Plan-then-confirm** keeps you from creating half-built or duplicate assets,
  because the create tools mutate the workspace.
- **Avatar first, then the round's interviewer** — the user picks the avatar (which
  sets voice/gender/language) before the interviewer is built inline with the round.
- **Pinning the enforced constraints** (weights = 100, Role-then-Round order, the
  round's nested `interviewer` object, rising thresholds, the two difficulty enums,
  the snake_case round / camelCase interviewer split, Session-based invites with
  idempotency) targets exactly where these setups usually break.