list_availability
List availability slots
All MCP toolsRead
Start with this to see the person's current FUTURE availability slots (already-ended intervals are hidden), start ascending, each marked manual (entered by hand) or agent (entered by a connected agent). Paginated by keyset cursor: pass the returned nextCursor as the next call's cursor to continue; null nextCursor = the final page. Availability slots are the person's own free-time windows: real date-time intervals, one organization-wide list per person, used ONLY to narrow proposed interview slots — their contents are never disclosed to the other side (a candidate's slots are invisible to companies, an interviewer's slots are invisible to candidates). Check the person's calendar on your side before writing; matchwire never reads their calendar. The response also carries the person's short-notice period: leadTime is their own setting (null when unset; the product default is one calendar day; set_person_interview_lead_time changes it) and boundary is the instant that period ends, drawn at call time in the person's saved time zone (UTC when unset; their own screen draws it in the device's zone instead, so set_person_time_zone keeps the two in step). While the person has availability registered, their own screen lists a proposed interview slot that starts before boundary, like one outside their availability, as out of the options, and the entrusted coordinator answers only slots on or after it inside the availability; with no availability registered the screen shows every slot and applies no boundary. A filtering of the choice, never a refusal: respond_interview_slot passes with the same meaning as that screen, so judge which slots fit from these slots, boundary, and the person's own intent. An interviewing staff member has no short-notice setting surface: for them leadTime reads null and boundary is the default.
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": "The person whose availability to read (persons.id — self)."
},
"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": [
"personId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Output 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)$"
},
"slots": {
"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 slot (availability_slots.id)."
},
"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 person who owns the slot (persons.id)."
},
"startsAt": {
"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 slot starts (ISO 8601, UTC)."
},
"endsAt": {
"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 slot ends (ISO 8601, UTC), always after startsAt."
},
"source": {
"type": "string",
"enum": [
"manual",
"note",
"agent"
],
"description": "Who entered the slot: 'manual' = the person by hand, 'note' = converted from the time bands the person wrote, 'agent' = a connected agent."
},
"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 slot row was created (ISO 8601, UTC)."
}
},
"required": [
"id",
"personId",
"startsAt",
"endsAt",
"source",
"createdAt"
],
"additionalProperties": false,
"description": "One real date-time interval the candidate is available in — organization-wide, person-owned, never disclosed to the counterpart."
},
"description": "One page of future slots, start ascending — the choke point's order."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass as the next call's cursor to continue; null on the final page."
},
"leadTime": {
"anyOf": [
{
"type": "object",
"properties": {
"value": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many units of lead the person wants; 0 = offer up to now."
},
"unit": {
"type": "string",
"enum": [
"day",
"hour"
],
"description": "How the lead value counts: 'day' = calendar days in the person's time zone (the boundary lands on a local midnight), 'hour' = rolling hours from now."
}
},
"required": [
"value",
"unit"
],
"additionalProperties": false,
"description": "The person's interview lead-time setting: how far ahead a proposed slot must start for their own screen to offer it as a choice while they have availability registered (the calendar hatches the period before that). Display only — it refuses no accept, the person's or their agent's; the entrusted coordinator answers only the slots that screen offers (on or after the boundary, inside the availability)."
},
{
"type": "null"
}
],
"description": "The person's own short-notice period setting, or null when unset (readers then apply the product default: one calendar day). The same value on every page."
},
"boundary": {
"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": "Where the short-notice period ends (ISO 8601, UTC), drawn at call time in the person's saved time zone (UTC when unset); never before now. While the person has availability registered, their own screen offers a proposed slot as a choice only if it starts at or after this instant, and the entrusted coordinator picks only such slots. The same value on every page."
}
},
"required": [
"personId",
"slots",
"nextCursor",
"leadTime",
"boundary"
],
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false
}