get_evaluation_request
Get one evaluation request
All MCP toolsRead
One evaluation request with its per-candidate evaluated flags and saved evaluations (the evaluator's overall grade, typed aspect answers, and comment on THIS request), the derived status, and the request lane's CURRENT evaluation aspects (aspects: label, type, options for choice/multi, required — in form order, the questions save_evaluation_request_item answers by index; a manual request reads the document-screening lane, a workflow-filed one the interview lane; a saved items[].evaluation.aspectAnswers is the snapshot taken at save time and does not move when the form changes). The request's seat is a job (jobId) or the agreed terms (agreementId) — exactly one; on the agreed terms the lane declares no aspects, so aspects is [] and a save keeps only the grade and the note. Visibility is the requester, the evaluator, and admins ONLY — every other viewer, cross-organization reach, and an unknown id get ONE indistinguishable not-found refusal (no existence oracle). Ids and flags only — no candidate content is returned, so nothing is logged as an impression. Person-id inputs name the human principal you act for (persons.id), never a credential identity: pass the staff member on whose behalf the call is made.
Input schema
{
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The request to fetch (evaluation_requests.id)."
},
"viewerPersonId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The viewing staff member (persons.id) — must be requester, evaluator, or admin."
}
},
"required": [
"requestId",
"viewerPersonId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output schema
{
"type": "object",
"properties": {
"request": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The request id (evaluation_requests.id)."
},
"jobId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "The job the evaluation is against (jobs.id, same organization) when the request's seat is a job's; null when the interview was on the agreed terms."
},
"agreementId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "The agreed terms the interview referred to (agreements.id) when the request's seat is the agreement's; null on a job seat — exactly one of jobId / agreementId is set, and the agreed terms declare no aspects."
},
"requesterPersonId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "The requesting staff member (persons.id), or null for a workflow-filed request."
},
"evaluatorPersonId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The staff member asked to evaluate (persons.id)."
},
"origin": {
"type": "string",
"enum": [
"manual",
"interview"
],
"description": "How the request was filed: manual (a staff member) | interview (the post-interview workflow)."
},
"interviewSlotId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"description": "The interview the workflow filed this request for (interview_slots.id), else null."
},
"status": {
"type": "string",
"enum": [
"open",
"completed",
"canceled"
],
"description": "Derived evaluation-request status: open | completed | canceled (never stored)."
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "When the request was filed (ISO 8601, UTC)."
},
"canceledAt": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
{
"type": "null"
}
],
"description": "When the request was canceled, or null while it stands."
},
"items": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"personId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The candidate to evaluate (persons.id, same organization)."
},
"evaluated": {
"type": "boolean",
"description": "Whether the evaluator has saved an evaluation for this candidate on this request."
},
"evaluation": {
"anyOf": [
{
"type": "object",
"properties": {
"grade": {
"anyOf": [
{
"type": "string",
"enum": [
"S",
"A",
"B"
],
"description": "Candidate evaluation grade: S | A | B (S = most want to meet). No C grade — declined owns rejection."
},
{
"type": "null"
}
],
"description": "The overall grade (S | A | B), or null."
},
"aspectAnswers": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"aspect": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The aspect text as it read when the evaluation was saved (a snapshot)."
},
"type": {
"type": "string",
"const": "choice"
},
"answer": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "The selected option's text, exactly as the form spells it."
}
},
"required": [
"aspect",
"type",
"answer"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"aspect": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The aspect text as it read when the evaluation was saved (a snapshot)."
},
"type": {
"type": "string",
"const": "multi"
},
"answer": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"description": "The selected options' texts, distinct, exactly as the form spells them."
}
},
"required": [
"aspect",
"type",
"answer"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"aspect": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The aspect text as it read when the evaluation was saved (a snapshot)."
},
"type": {
"type": "string",
"const": "text"
},
"answer": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "The free-text answer, trimmed, non-empty, ≤ 300 chars."
}
},
"required": [
"aspect",
"type",
"answer"
],
"additionalProperties": false
}
],
"description": "One saved aspect answer — the aspect text snapshot, its type, and the typed answer. Unanswered aspects have no entry."
},
"description": "The aspects as ANSWERED at save time, in the form's order then — unanswered aspects have no entry."
},
"note": {
"type": "string",
"maxLength": 300,
"description": "The comment — the reason behind the judgement, read by whoever asked. ≤ 300 chars."
},
"evaluatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "When the evaluation was first saved (ISO 8601, UTC)."
}
},
"required": [
"grade",
"aspectAnswers",
"note",
"evaluatedAt"
],
"additionalProperties": false,
"description": "One evaluator's saved evaluation of one candidate on one request."
},
{
"type": "null"
}
],
"description": "The saved evaluation, or null while the evaluator has not saved one."
}
},
"required": [
"personId",
"evaluated",
"evaluation"
],
"additionalProperties": false,
"description": "One evaluation-request item: the candidate, the evaluated flag, and the saved evaluation."
},
"description": "The requested candidates with their derived evaluated flags."
}
},
"required": [
"id",
"jobId",
"agreementId",
"requesterPersonId",
"evaluatorPersonId",
"origin",
"interviewSlotId",
"status",
"createdAt",
"canceledAt",
"items"
],
"additionalProperties": false,
"description": "The request with the items' CURRENT evaluated flags."
},
"aspects": {
"maxItems": 10,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "choice"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The question the aspect asks."
},
"required": {
"type": "boolean"
},
"options": {
"minItems": 2,
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"description": "The options the designer wrote, in display order — distinct, 2–5, each ≤ 30 chars."
}
},
"required": [
"type",
"label",
"required",
"options"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "multi"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The question the aspect asks."
},
"required": {
"type": "boolean"
},
"options": {
"minItems": 2,
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"description": "The options the designer wrote, in display order — distinct, 2–5, each ≤ 30 chars."
}
},
"required": [
"type",
"label",
"required",
"options"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "text"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "The question the aspect asks."
},
"required": {
"type": "boolean"
}
},
"required": [
"type",
"label",
"required"
],
"additionalProperties": false
}
],
"description": "One evaluation aspect: choice (pick one option) | multi (all that apply) | text (free text)."
},
"description": "The request lane's CURRENT evaluation aspects in form order — the index space of save_evaluation_request_item's aspectAnswers; [] when the lane has no aspects."
}
},
"required": [
"request",
"aspects"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}