save_availability

All MCP toolsWrite

Add real date-time intervals to the person's availability list, as their connected agent (rows are marked agent-entered). All slots land in one transaction — any invalid reference refuses the WHOLE call with zero writes. A slot identical to an existing future slot is skipped silently (re-sending is idempotent), and skipped slots do not count in `added`. 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. Before saving or deleting, call list_availability first to see the current future slots.

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 write (persons.id — self)."
    },
    "slots": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "startsAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the slot starts, ISO 8601 datetime — Z or ±hh:mm offset accepted, stored as UTC."
          },
          "endsAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the slot ends, ISO 8601 datetime — Z or ±hh:mm offset accepted, stored as UTC; must be after startsAt."
          }
        },
        "required": [
          "startsAt",
          "endsAt"
        ],
        "additionalProperties": false
      },
      "description": "The intervals to add, 1..20 per call."
    }
  },
  "required": [
    "personId",
    "slots"
  ],
  "$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)$"
    },
    "added": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "How many rows were actually inserted — duplicates of existing future slots are skipped and not counted."
    },
    "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": "The rows actually inserted, in input order (skipped duplicates omitted)."
    }
  },
  "required": [
    "personId",
    "added",
    "slots"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}