save_intent

All MCP toolsWrite

Merge the person's intent fields — mobility (3 levels), sideJobDesire, availability — into their canonical CandidateProfile (versioned; absent keys stay unchanged) and echo each CHANGED axis into the availability_signals capture. openToWork is DERIVED from mobility (ADR-0084): true iff mobility is "open_to_move" or above — the deprecated openToWork input is accepted only when it matches that derivation and refused (nothing written) when it contradicts it. Use get_candidate_profile.version as expectedVersion.

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 intent is being saved (persons.id — self)."
    },
    "intent": {
      "type": "object",
      "properties": {
        "mobility": {
          "description": "Mobility: one of the ordered 3 levels (the intent UI writes only these).",
          "type": "string",
          "enum": [
            "not_looking",
            "open_to_move",
            "actively_looking"
          ]
        },
        "sideJobDesire": {
          "type": "string",
          "enum": [
            "not_open",
            "open"
          ],
          "description": "Side-job desire: \"open\" or \"not_open\". Orthogonal to mobility."
        },
        "openToWork": {
          "description": "DEPRECATED (ADR-0084): openToWork is DERIVED from mobility — true iff mobility is \"open_to_move\" or above — and can no longer be set independently. Omit it; a value that matches the derived one is accepted for backward compatibility, a contradicting value is refused and nothing is written.",
          "type": "boolean"
        },
        "availability": {
          "type": "object",
          "properties": {
            "earliestStartDate": {
              "type": "string",
              "pattern": "^[1-2]\\d{3}(-[0-1]\\d(-[0-3]\\d)?)?$",
              "description": "Earliest start date as ISO 8601 with optional month/day, e.g. \"2026-10\" or \"2026-10-01\"."
            },
            "weeklyHours": {
              "description": "Available hours per week as a positive integer.",
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            }
          },
          "additionalProperties": false,
          "description": "Availability window: earliest start date and weekly available hours (both optional)."
        }
      },
      "additionalProperties": false,
      "description": "Intent fields to merge into the profile; absent keys stay unchanged."
    },
    "expectedVersion": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "The version you loaded (get_candidate_profile.version) — a stale value refuses with a version conflict naming expected and latest; re-read and retry."
    }
  },
  "required": [
    "personId",
    "intent",
    "expectedVersion"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Output schema

{
  "type": "object",
  "properties": {
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The newly appended profile version."
    },
    "emittedSignalKinds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One availability_signals kind per CHANGED axis, in emission order — empty when nothing captured changed (openToWork and weeklyHours alone emit nothing)."
    }
  },
  "required": [
    "version",
    "emittedSignalKinds"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}