diff --git a/crates/openpencil-shell-core/src/mcp.rs b/crates/openpencil-shell-core/src/mcp.rs
index ae24a2fd0..1c91c5b3b 100644
--- a/crates/openpencil-shell-core/src/mcp.rs
+++ b/crates/openpencil-shell-core/src/mcp.rs
@@ -196,6 +196,12 @@ pub enum McpCommand {
     /// carry children / a full subtree once a JSON Node parser
     /// lives on the host. The current contract matches what TS
     /// `replace_node` accepts for primitives, minus children.
+    ///
+    /// **Destructive on containers**: replacing a Frame / Group
+    /// / node-with-children drops every descendant of the old
+    /// node without warning. Use `update_node` to patch a
+    /// container in place; reserve `replace_node` for primitive
+    /// → primitive swaps where the loss is intended.
     ReplaceNode {
         node_id: u64,
         kind: String,
diff --git a/crates/openpencil-shell-core/src/mcp/write_tools.rs b/crates/openpencil-shell-core/src/mcp/write_tools.rs
index 4d12af52f..fcce37046 100644
--- a/crates/openpencil-shell-core/src/mcp/write_tools.rs
+++ b/crates/openpencil-shell-core/src/mcp/write_tools.rs
@@ -514,6 +514,12 @@ pub fn copy_node_snapshot() -> CopyNode {
 /// children of the replacement default to empty). TS-equivalent
 /// behavior for primitives; subtree-replacement requires a JSON
 /// Node parser that doesn't live on this side yet.
+///
+/// **Destructive on containers**: replacing a Frame / Group / node
+/// with children drops every descendant of the old node without
+/// warning. Use `update_node` to patch a container in place;
+/// reserve `replace_node` for primitive → primitive swaps where
+/// the loss is intended.
 pub struct ReplaceNode;
 
 impl McpTool for ReplaceNode {