get_candidate_evaluation
Get candidate evaluation
All MCP toolsRead
THE organization-level evaluation of one candidate: grade (S/A/B, S = most want to meet) and the one-line note. Never-evaluated is a normal answer (evaluated: false), not a refusal. requestEvaluations lists the evaluations saved through evaluation requests for this candidate (evaluator, the request's seat — a job (jobId) or the agreed terms (agreementId), exactly one —, origin, overall grade, aspect grades as graded then, comment, first-save instant), newest first, up to 50, read with the VIEWER's visibility: the candidate room's full staff only (a non-member or evaluator-seat viewer reads []), and an assignee-only job's rows are absent for a non-assignee; a row on the agreed terms names no job and follows the room gate alone. The organization-level evaluation and these rows are different facts, never merged. A single deliberate retrieval — no impression is logged.
Input schema
{
"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": "persons.id — from candidate browse or a member listing."
},
"viewerPersonId": {
"description": "The viewing staff member (persons.id) whose job visibility the request evaluations are read with. A person-bound credential may omit it (its own person is the viewer); an unbound service key names a member of its own organization, or requestEvaluations is [].",
"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)$"
}
},
"required": [
"personId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output schema
{
"type": "object",
"properties": {
"evaluated": {
"type": "boolean",
"description": "False when the organization has never evaluated this person."
},
"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 grade (S | A | B), or null when ungraded."
},
"note": {
"type": "string",
"maxLength": 2000,
"description": "The one-line note — the reason for the grade, read by whoever requested the evaluation. Erasable free text, never captured; stored ceiling 2000 chars (legacy memos + folded sticky labels), changed values are capped at 300 on write."
},
"updatedAt": {
"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 last changed (ISO 8601, UTC)."
}
},
"required": [
"grade",
"note",
"updatedAt"
],
"additionalProperties": false,
"description": "One organization-level candidate evaluation: grade (S/A/B, nullable) + the one-line note + updatedAt."
},
{
"type": "null"
}
],
"description": "The working state; null when never evaluated."
},
"requestEvaluations": {
"maxItems": 50,
"type": "array",
"items": {
"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 the evaluation was saved on (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 request was against (jobs.id, same organization) when its 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."
},
"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 who saved the evaluation (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 the request for (interview_slots.id), else null."
},
"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) — the newest-first sort key."
},
"evaluation": {
"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."
}
},
"required": [
"requestId",
"jobId",
"agreementId",
"evaluatorPersonId",
"origin",
"interviewSlotId",
"evaluatedAt",
"evaluation"
],
"additionalProperties": false,
"description": "One saved evaluation of one person on one request: the request facts (request, its seat — a job or the agreed terms —, evaluator, origin, interview) and the evaluation as graded then."
},
"description": "The rollup of evaluations saved across live requests for this candidate, newest first, read with the viewer's visibility; [] when none, when the viewer is not a full staff member (non-member or evaluator seat), or when an unbound key names nobody."
}
},
"required": [
"evaluated",
"evaluation",
"requestEvaluations"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}