list_proposal_options
List the jobs you may propose to a candidate
All MCP toolsRead
The proposal picker for one candidate: every published job of your organization, with proposable (false when the person's registered conditions exclude it — no reason is given), the pair's origin (matched by the engine, or the person's own interested from search) where a pair is formed, the standing proposal state (waiting / mutual / passed — a passed job may be proposed again), and the job's key facts — and the row for terms independent of any job posting (terms): always proposable, with its standing state (waiting / mutual / passed). Empty (jobs [], terms null) for a person the organization may not see (never matched, never interested) — propose_jobs refuses such a person with pair_not_formed. actorPersonId is the human principal you act for (persons.id), never a credential identity: candidate agents pass the candidate, employer agents pass the hiring-side member. Paginated by keyset cursor: pass the returned nextCursor as the next call's cursor to continue; null nextCursor = the final page. Occupation references in the answer carry name as the display name in the saved language of the person this call acts for (the bound person, or the person named as the one acted for on the caller's own side; a service key acting for nobody reads the connection's language) — read the id as the identity, never the name.
Input schema
{
"type": "object",
"properties": {
"actorPersonId": {
"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 acting hiring-side member (persons.id) — the picker is read as theirs."
},
"personToken": {
"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, as an opaque subject_token (from match results or list_job_interests)."
},
"limit": {
"description": "Page size, 1..50 (default 20).",
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"description": "Opaque continuation token — the previous page's nextCursor. Omit for the first page.",
"type": "string",
"minLength": 1
}
},
"required": [
"actorPersonId",
"personToken"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output schema
{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobId": {
"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": "One of the organization's published jobs (jobs.id)."
},
"title": {
"type": "string",
"maxLength": 1000,
"description": "The job's title."
},
"proposable": {
"type": "boolean",
"description": "false ⇔ the person's registered conditions exclude the job (the engine's own eligibility predicate) — it cannot be proposed, and no reason is given."
},
"origin": {
"description": "Present only on a formed pair — how the person came into view under this job.",
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"matched",
"expressed_interest"
],
"description": "\"matched\" — the engine showed the person under this job; \"expressed_interest\" — the person said interested from search."
},
"at": {
"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": "The earliest exposure, or the standing interested's instant (ISO 8601, UTC)."
}
},
"required": [
"kind",
"at"
],
"additionalProperties": false
},
"note": {
"description": "The note the person sent with their standing interested on this job — read it before proposing; absent when none.",
"type": "string"
},
"current": {
"anyOf": [
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"waiting",
"mutual",
"passed"
],
"description": "\"waiting\" (proposed, awaiting the answer), \"mutual\", or \"passed\" (the person passed — you can propose again)."
},
"at": {
"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 that state was reached (ISO 8601, UTC)."
},
"threadId": {
"description": "The pair's open chat on a mutual state; absent otherwise.",
"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"
}
]
}
},
"required": [
"state",
"at"
],
"additionalProperties": false,
"description": "The standing state of one proposal row."
},
{
"type": "null"
}
],
"description": "The pair's standing proposal state; null when nothing stands."
},
"facts": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The denormalized `jobs.title` column (both readers carry it)."
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Read-time excerpt of posting.description, truncated to 160 code points; null when the posting has no description."
},
"baseSalary": {
"type": "object",
"properties": {
"currency": {
"default": "JPY",
"description": "ISO 4217 currency code (exactly three uppercase letters). Defaults to \"JPY\".",
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"min": {
"description": "Lower bound of the range as a non-negative integer; must be <= max when both are present.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"max": {
"description": "Upper bound of the range as a non-negative integer; must be >= min when both are present.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unit": {
"default": "YEAR",
"description": "Salary period unit: \"YEAR\" (annual amounts, the default), \"MONTH\", or \"HOUR\".",
"type": "string",
"enum": [
"YEAR",
"MONTH",
"HOUR"
]
}
},
"required": [
"currency",
"unit"
],
"additionalProperties": false,
"description": "Salary range in a single ISO 4217 currency (non-negative integers, min <= max); the period is given by `unit` (annual by default)."
},
"remote": {
"type": "string",
"enum": [
"none",
"hybrid",
"full"
],
"description": "Remote-work classification: \"none\" (on-site), \"hybrid\", or \"full\" (fully remote). Other values are rejected; absent = undisclosed. \"Full remote within Japan\" composes as remote \"full\" + applicantLocation countries [\"JP\"]."
},
"employmentType": {
"type": "string",
"enum": [
"FULL_TIME",
"PART_TIME",
"CONTRACTOR",
"TEMPORARY",
"INTERN"
],
"description": "Employment type (schema.org vocabulary): \"FULL_TIME\", \"PART_TIME\", \"CONTRACTOR\", \"TEMPORARY\", or \"INTERN\". Other values are rejected."
},
"jobLocation": {
"description": "Work location as ONE ISO 3166-2 subdivision code, e.g. \"JP-13\" (the deprecated single field, same shape as jobPostingSchema); readers use jobLocationsOf over the fragment.",
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
},
"jobLocations": {
"description": "Work locations as a mixed country/region list, e.g. [\"JP-13\", \"JP-27\"] (any of the listed sites) or [\"JP\"] (anywhere within the country), unique and insertion-order-preserving. An empty array is rejected — absent = undisclosed (the same meaning as the deprecated single `jobLocation` being absent). Readers of the single `jobLocation` migrate to this list via `jobLocationsOf`; a redundant country⊇region pair is accepted (the desiredLocations posture — the UI absorbs it, matching is unaffected).",
"minItems": 1,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code: exactly two uppercase letters, e.g. \"JP\". Three-letter codes (\"JPN\"), subdivision codes (\"JP-13\"), country names, and lowercase are rejected."
},
{
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$",
"description": "ISO 3166-2 subdivision code: two uppercase letters, a hyphen, then 1-3 uppercase alphanumerics, e.g. \"JP-13\" (Tokyo). Country-only codes (\"JP\"), place names, and lowercase are rejected."
}
],
"description": "Desired-location entry: a whole country as an ISO 3166-1 alpha-2 code (e.g. \"US\") or one region as an ISO 3166-2 subdivision code (e.g. \"JP-13\"). Names, lowercase, and three-letter codes are rejected."
}
},
"occupations": {
"description": "Job occupations: references { id, name? } to occupation rows, unique by id, in the order stated. An empty array is rejected — absent = unclassified (the house nonempty-optional pattern). Parallel to (never replacing) the raw `title` verbatim.",
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"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 occupation's number (an `occupations` row) — the identity predicates count on."
},
"name": {
"description": "The row's display name in the reader's language, added when a read answers (trimmed, non-empty). Optional on a write and never stored — a stored reference carries the number alone.",
"type": "string",
"pattern": "^\\S(?:[\\s\\S]*\\S)?$"
}
},
"required": [
"id"
],
"additionalProperties": false,
"description": "Occupation reference: { id, name? } — the row's number, plus the display name a read adds in the reader's language (a write may carry one; it is not stored)."
}
},
"published": {
"type": "boolean",
"description": "Published ⇔ true (the ADR-0082 visibility fact) — false renders the no-longer-published chip."
}
},
"required": [
"title",
"summary",
"published"
],
"additionalProperties": false,
"description": "The shared job-facts fragment (deriveJobFacts)."
}
},
"required": [
"jobId",
"title",
"proposable",
"current",
"facts"
],
"additionalProperties": false,
"description": "One row of the proposal picker: a published job and whether it can be proposed."
},
"description": "One page of the picker's rows in the organization's posting order; empty when nothing can be proposed."
},
"terms": {
"anyOf": [
{
"type": "object",
"properties": {
"current": {
"anyOf": [
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"waiting",
"mutual",
"passed"
],
"description": "\"waiting\" (proposed, awaiting the answer), \"mutual\", or \"passed\" (the person passed — you can propose again)."
},
"at": {
"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 that state was reached (ISO 8601, UTC)."
},
"threadId": {
"description": "The pair's open chat on a mutual state; absent otherwise.",
"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"
}
]
}
},
"required": [
"state",
"at"
],
"additionalProperties": false,
"description": "The standing state of one proposal row."
},
{
"type": "null"
}
],
"description": "The pair's latest agreement record as the picker reads it: \"waiting\" (a record awaits the person's answer — a terms proposal, or one the company recorded in the chat), \"mutual\" (the person proceeded — the agreed terms are, or were, the chat's topic), \"passed\" (the person declined — you can propose again); null when nothing stands."
}
},
"required": [
"current"
],
"additionalProperties": false,
"description": "The proposal picker's terms row — terms independent of any job posting — always proposable; nothing of the terms is recorded."
},
{
"type": "null"
}
],
"description": "The picker's terms row (propose it with propose_jobs { terms: true }); null for a person the organization may not see. On every page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as the next call's cursor to continue; null on the final page."
}
},
"required": [
"jobs",
"terms",
"nextCursor"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}