Set Annotations

Added value: +false

Removed value: -{
-  "description": "If updating: ID of the existing annotation",
-  "type": "string"
-}

Previous value: -"The ID of the category"New value: +"Optional annotation category ID from annotation_list"

Added value: +{
+  "description": "Markdown annotation text; required and rejected when blank",
+  "type": "string"
+}

Previous value: -"Expected name of the node (verification)"New value: +"The node's current exact name, passed back verbatim from `node_info`."

Removed value: -{}

Previous value: -"Custom metadata properties"New value: +"Optional duplicate-free Figma annotation property references. The enum is the full catalogue; Figma gates each entry by node type and refuses the append for one the target node does not support (e.g. 'fontSize' on a RECTANGLE), so a rejection here is a per-row failure rather than a schema error. Omit this field unless the property is clearly one the target node has."

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "description": "The annotated Figma property",
+      "enum": [
+        "width",
+        "height",
+        "maxWidth",
+        "minWidth",
+        "maxHeight",
+        "minHeight",
+        "fills",
+        "strokes",
+        "effects",
+        "strokeWeight",
+        "cornerRadius",
+        "textStyleId",
+        "textAlignHorizontal",
+        "fontFamily",
+        "fontStyle",
+        "fontSize",
+        "fontWeight",
+        "lineHeight",
+        "letterSpacing",
+        "itemSpacing",
+        "padding",
+        "layoutMode",
+        "alignItems",
+        "opacity",
+        "mainComponent",
+        "gridRowGap",
+        "gridColumnGap",
+        "gridRowCount",
+        "gridColumnCount",
+        "gridRowAnchorIndex",
+        "gridColumnAnchorIndex",
+        "gridRowSpan",
+        "gridColumnSpan"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "type": "object"
+}

Removed value: -{
-  "type": "string"
-}

Previous value: -"object"New value: +"array"

Removed value: -{
-  "description": "Annotation status",
-  "enum": [
-    "TODO",
-    "DONE",
-    "NONE"
-  ],
-  "type": "string"
-}

Previous value: -[
-  "nodeId",
-  "nodeName",
-  "categoryId"
-]New value: +[
+  "nodeId",
+  "nodeName",
+  "labelMarkdown"
+]

Added value: +1

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "description": "Stable machine-readable failure code (see the error playbook)",
+      "type": "string"
+    },
+    "details": {
+      "description": "Optional structured context (e.g. partialMutation, before-values)"
+    },
+    "message": {
+      "description": "Human/agent-readable message embedding its own recovery",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Number of failed annotations",
+  "type": "number"
+}

Added value: +{
+  "description": "Number of requested annotations",
+  "type": "number"
+}

Previous value: -"Detailed execution results"New value: +"Detailed execution results with before/after annotation counts (one row per input, in input order)"

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "afterCount": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Verified annotation count after this row's attempt, or null when post-attempt state is unknown"
+    },
+    "afterCountVerified": {
+      "description": "Whether afterCount is a verified observation (false requires afterCount:null)",
+      "type": "boolean"
+    },
+    "before": {
+      "description": "Q9/Q24: diagnostic evidence of the known pre-mutation state; not guaranteed to be a directly executable restoring-write input"
+    },
+    "beforeCount": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Verified annotation count immediately before this row, or null when the count could not be read"
+    },
+    "beforeCountVerified": {
+      "description": "Whether beforeCount is a verified observation (false requires beforeCount:null)",
+      "type": "boolean"
+    },
+    "error": {
+      "description": "Actionable reason, REQUIRED on any non-success row (Q25 contract key)",
+      "type": "string"
+    },
+    "nodeId": {
+      "description": "Identity of the target node (Q25 contract key)",
+      "type": "string"
+    },
+    "outcomeUnknown": {
+      "const": true,
+      "description": "Present when an append was attempted but post-attempt state could not be verified; never retry blindly",
+      "type": "boolean"
+    },
+    "partialMutation": {
+      "description": "Q9/Q24: set when the item mutated before it failed",
+      "type": "boolean"
+    },
+    "postStateError": {
+      "description": "Secondary readback failure explaining why annotation state is unknown; the row error remains the initiating failure",
+      "type": "string"
+    },
+    "status": {
+      "description": "Per-item outcome (Q25 contract key)",
+      "enum": [
+        "success",
+        "failed",
+        "skipped"
+      ],
+      "type": "string"
+    },
+    "success": {
+      "description": "Legacy per-row boolean; mirrors status === 'success'",
+      "type": "boolean"
+    },
+    "whatChanged": {
+      "description": "Q9/Q24: plain-language statement of what changed",
+      "type": "string"
+    }
+  },
+  "required": [
+    "nodeId",
+    "status",
+    "beforeCount",
+    "afterCount",
+    "beforeCountVerified",
+    "afterCountVerified"
+  ],
+  "type": "object"
+}

Added value: +"array"

Added value: +{
+  "description": "Number of skipped annotations",
+  "type": "number"
+}

Added value: +{
+  "description": "Overall status of the batch operation",
+  "enum": [
+    "success",
+    "partial_success",
+    "failed"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Number of succeeded annotations",
+  "type": "number"
+}

Previous value: -"Whether annotations were set successfully"New value: +"Whether all annotations were set successfully"

Previous value: -falseNew value: +{}

Added value: +false