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 reusable AI persona + scorecard that *runs* a Round.
  Tool: `create_interviewer`. ID: `interviewer_id`.
- **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/assessment, the skills, the
  objective, 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`) requires **both** `role_id` and `interviewer_id`. Neither
exists until you create it, so build in this order:

```
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. Interviewers  (create_interviewer)         → set ai_avatar_id to the chosen avatar; capture each interviewer_id
2. Role          (create_role)                → capture the role_id
3. Rounds        (create_round)               → reference IDs from steps 1 & 2
4. Participants  (create_participant, …)      → only when adding candidates
5. Sessions      (create_session)             → schedules the interview, sends invite
```

Building out of order means a 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_interviewer`. Don't pick one
silently or default to "no avatar" — surface the list and let them decide.

## 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 a public Google Drive URL of the
job description** so it can be attached to the Role (see "Attachments" below). Ask
once, make it optional, and proceed without it if the user doesn't have one — never
block the build waiting on a link. **If the user pasted the JD as text and has no
link, do not skip the attachment: generate a PDF from the JD text yourself, upload
it with `upload_file` (`purpose: "knowledge_base"`), and attach the returned URL to
the Role's `knowledge_base_links`** (see "JD text → PDF → upload" under Attachments).

**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_interviewers` to find reusable Interviewers, `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.
Fold the findings into the plan ("I'll reuse your existing *ITOM Specialist*; 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.
- **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`, `objective`, 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 an 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. Then call `list_interviewers` and
  **reuse a matching one** instead of duplicating it. Build **narrow,
  single-purpose** Interviewers (e.g. "ITOM Specialist", "Friendly Screener"), not
  one giant do-everything expert. A new variant of a Role should just add a Round
  pointing at an existing Interviewer, not rebuild personas.
- **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 Interviewer/Role/Round, `get_*` it (`get_interviewer`, `get_role`,
  `get_round`) to confirm it resolves and to read its real fields, 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 — MCP tools vs the raw REST API
The **MCP tools are all snake_case**, `create_interviewer` included: `use_case`,
`evaluation_dimensions`, `additional_instructions`, `ai_avatar_id`, `is_public`,
alongside `template_name`, `role_id`, `stage_order`, `pass_threshold`,
`candidate_id`. Use snake_case for every MCP call. Only the **raw REST API** (`POST
/api/v1/interviewers`) takes camelCase (`useCase`, `evaluationDimensions`,
`additionalInstructions`, `isPublic`) — the MCP server translates for you, so don't
send camelCase to a tool. Mixing the two is the most common cause of silent
validation failures.

### Interviewer required fields
`name`, `persona` (how the AI introduces itself at the start of a session),
`use_case`, and `evaluation_dimensions`. Skipping `persona` is a common miss — write
a 1–2 sentence in-character opener.

**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
`evaluation_dimensions` 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
`additional_instructions` and fill `context` — which is an object
`{organizationContext?, domainContext?, scenarioContext?}`, not a single string —
the live AI interviewer reads these directly. Optionally tune `interaction`
(`tone`, `style`, `difficulty`, `probingDepth`), `scoring` (`scale`,
`scoringMethod`), and `output`.

### AI instruction must force separate evaluation-dimension feedback
Every Interviewer and every Round `additional_instructions` / `ai_instructions` 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 interviewer and round 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`, `description` (1–3 sentence overview), and `objective`
(what the interview should determine). `description` is required and often
forgotten. `success_outcome` is auto-derived from `use_case` if omitted but is
safer to set explicitly. Useful optional fields: `domain`, `level`, `requirements`,
`skills`, `soft_skills`, `additional_notes`, `default_difficulty`,
`default_session_mode`, `visibility`. (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 | require_reviewer_approval`** (default
`none`). Use `auto_advance` for early rounds; put `require_reviewer_approval`
**before a final or high-stakes round** so a human signs off. (Older values like
`auto_advance_if_passed`, `auto_reject_if_failed`, `auto_assign_next_stage` are
deprecated — don't use them.)

### 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:

- **Role / JD** — when creating or refining a Role, ask for a public Drive link to
  the job description and attach it via the Role's `knowledge_base_links` (array
  of strings). The JD then grounds the rubric and the live interview. **If the user
  pasted the JD as text instead of a link, generate a PDF and upload it** — see
  "JD text → PDF → upload" below. Every Role should end up with the JD attached.
- **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%).

### JD text → PDF → upload (do this whenever the JD arrives as pasted text)

When the user pastes the JD as plain text and has no Drive link, attach it anyway
by converting it yourself. Run this after the Role is created (approval for the
build covers this step — no extra confirmation needed):

1. **Generate a PDF** of the JD with reportlab (Python) in the container,
   preserving the JD verbatim — same sections, same bullets, no rewording. A
   one-line header with company / location / experience / work mode is fine.
2. **Base64-encode** it (`base64 -w0 file.pdf`) and call `upload_file` with
   `{filename: "<Role> JD.pdf", content_base64, purpose: "knowledge_base"}`.
3. **Attach** the returned `url` to the Role via `update_role`
   `knowledge_base_links` (append to any existing links — the field replaces
   wholesale). Confirm the response's `knowledge_base_extracted` populated, which
   verifies Intervyo parsed the JD.

Never fabricate a URL, and never skip the attachment just because the JD came as
text — a Role grounded in the actual JD interviews better.

### 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 Interviewer from a JD (approval-gated)

When the user wants **one Interviewer for a specific JD** (rather than a whole Role
+ Rounds 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 final
   Interviewer must **reuse** a real `ai_avatar_id` from this list — do **not** call
   `create_ai_avatar` unless the user explicitly asks for a new avatar (an avatar is
   a name + gender + voice + language; no image).
2. **List existing interviewers.** Call `list_interviewers` and review them.
   Read-only — create or change nothing yet.
3. **Reuse first.** If an existing Interviewer covers the JD's skill area fully or
   partially, reuse or extend it. Propose a brand-new Interviewer **only** if none
   cover the required skills.
4. **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.
5. **Present the full proposed spec for approval** before creating or changing
   anything:
   - Persona name, inferred gender, and company/client name
   - The user-chosen `ai_avatar_id` + its voice, gender, and **language**
   - Simple first-person opening line (`persona`) using the company/client name, under 200 characters
   - `use_case`
   - 3–5 `evaluation_dimensions` with weights summing to **exactly 100**
   - Each dimension mapped to a specific JD requirement
   - Recommendation: **reuse / extend / create new** — with reasoning
6. **Stop and wait** for explicit approval.
7. **Execute the approved spec only after the user confirms** — `create_interviewer`
   (or `update_interviewer` when extending), using the valid `ai_avatar_id`.

Attach the JD itself for grounding: ask for a public Google Drive link and put it
in the Role's `knowledge_base_links`, or pass JD text directly. If a Drive fetch
fails, tell the user to set sharing to "anyone with the link."

## 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 |
| 1 | platform | Platform Fundamentals | 45 min | 70 | auto_advance |
| 2 | itom | ITOM Specialist | 45 min | 75 | auto_advance |
| 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 Interviewers + reuse** enforces the reusable-building-block
  model: the user picks the avatar (which sets voice/gender/language) before the
  Interviewer is built, and variants just add a Round instead of rebuilding personas.
- **Pinning the enforced constraints** (weights = 100, the `role_id` +
  `interviewer_id` chain, rising thresholds, the two difficulty enums, the
  camelCase vs snake_case asymmetry, Session-based invites with idempotency)
  targets exactly where these setups usually break.