basecoat-ui

Overview Schema Source Related Servers Discussions Admin

apply_design_patch

Idempotent

Commit atomic design graph operations to a UI session using expectedRevision and operationId; replay same operationId returns original receipt. Does not write source files.

Instructions

Apply one atomic list of design graph operations with expectedRevision and operationId. Replay with the same operationId returns the original receipt. A committed mutation always acknowledges success; oversized optional fields may be omitted with truncated:true. Does not write application source files.

Input Schema

Name	Required	Description
`designId`	Yes	Identifier of the design session to mutate.
`operations`	Yes	Ordered array of patch operations (add_node, remove_node, move_node, connect, disconnect, set_decision, set_binding).
`operationId`	Yes	Idempotency key for this patch transaction.
`expectedRevision`	Yes	Expected current revision of the session to guarantee optimistic concurrency.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.8.0Oct 15, 2026

addedInput schema / properties / designId / description

Added value: +"Identifier of the design session to mutate."

addedInput schema / properties / expectedRevision / description

Added value: +"Expected current revision of the session to guarantee optimistic concurrency."

addedInput schema / properties / operationId / description

Added value: +"Idempotency key for this patch transaction."

addedInput schema / properties / operations / description

Added value: +"Ordered array of patch operations (add_node, remove_node, move_node, connect, disconnect, set_decision, set_binding)."

Changed4 schema fields changedv1.6.2Oct 5, 2026

removedInput schema / properties / operations / items / additionalProperties
```
Removed value: -{}
```

addedInput schema / properties / operations / items / oneOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "op": {
+        "const": "instantiate_recipe",
+        "type": "string"
+      },
+      "pagePrefix": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "recipe": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "recipe",
+      "pagePrefix"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "bindings": {
+        "additionalProperties": {
+          "maxLength": 64,
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "type": "string"
+        },
+        "propertyNames": {
+          "maxLength": 64,
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "block": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      },
+      "node": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "attach_block",
+        "type": "string"
+      },
+      "order": {
+        "maximum": 10000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "parent": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "slot": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "parent",
+      "slot",
+      "node",
+      "block"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "block": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      },
+      "node": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "replace_block",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "node",
+      "block"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "node": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "remove_block",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "removeSubtree": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "node",
+      "removeSubtree"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "from": {
+        "additionalProperties": false,
+        "properties": {
+          "node": {
+            "maxLength": 64,
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "type": "string"
+          },
+          "port": {
+            "maxLength": 64,
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "node",
+          "port"
+        ],
+        "type": "object"
+      },
+      "id": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "connect_ports",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "relation": {
+        "enum": [
+          "controls",
+          "data"
+        ],
+        "type": "string"
+      },
+      "to": {
+        "additionalProperties": false,
+        "properties": {
+          "node": {
+            "maxLength": 64,
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "type": "string"
+          },
+          "port": {
+            "maxLength": 64,
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "node",
+          "port"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "id",
+      "relation",
+      "from",
+      "to"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "connection": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "disconnect_ports",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "connection"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "key": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      },
+      "op": {
+        "const": "set_decision",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "scope": {
+        "enum": [
+          "project",
+          "page"
+        ],
+        "type": "string"
+      },
+      "value": {
+        "anyOf": [
+          {
+            "maxLength": 200,
+            "type": "string"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "op",
+      "scope",
+      "key",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "node": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "op": {
+        "const": "record_written",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      },
+      "planDigest": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      },
+      "sourcePath": {
+        "maxLength": 260,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "page",
+      "node",
+      "sourcePath",
+      "planDigest"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "op": {
+        "const": "mark_plan_ready",
+        "type": "string"
+      },
+      "page": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "page"
+    ],
+    "type": "object"
+  }
+]

removedInput schema / properties / operations / items / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / operations / items / type
```
Removed value: -"object"
```

Addedv1.4.0Oct 1, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare idempotentHint=true and readOnlyHint=false, and the description meaningfully extends that: replay returns the original receipt, committed mutations always acknowledge success, oversized optional fields may be omitted with truncated:true, and it does not touch source files. This is substantive behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences that are front-loaded with the atomic-apply statement and follow with replay, acknowledgment/truncation, and scope boundary. No filler; each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by describing the return behavior (receipt on replay, success acknowledgment, truncated:true), and it covers concurrency and idempotency for a mutating tool. The omission is any explanation of the operation kinds themselves, though the schema's oneOf branches carry that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: operationId is positioned as a replay/idempotency key and expectedRevision as the concurrency guard, tying the parameters to their operational contract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Apply one atomic list of design graph operations' clearly names both the action and the target, and the closing 'Does not write application source files' carves out scope. It does not name a sibling alternative, but the graph-mutation domain is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Idempotency and concurrency requirements are explained ('Replay with the same operationId', 'with expectedRevision'), which imply the calling context, but there is no explicit when-to-use or when-not-to-use guidance relative to validate_design or the other design siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

apply_design_patch

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools