diff --git a/packages/mcp/build/lib/markdown-converter.js b/packages/mcp/build/lib/markdown-converter.js
index cbf6059f..c5511f19 100644
--- a/packages/mcp/build/lib/markdown-converter.js
+++ b/packages/mcp/build/lib/markdown-converter.js
@@ -212,9 +212,9 @@ export function convertProseMirrorToMarkdown(content) {
                 const imgCaption = node.attrs?.caption || "";
                 if (imgCaption) {
                     // ![]() can't carry a caption, so (symmetric to video) emit a raw
-                    // <img> wrapped in a block <div>. markdownToHtml passes it through and
-                    // the image extension's parseHTML restores the caption from
-                    // data-caption on import.
+                    // <img> wrapped in a block <div>. On import marked.parse keeps the raw
+                    // HTML and generateJSON runs the image extension's parseHTML, which
+                    // restores the caption from data-caption.
                     const parts = [`src="${escapeAttr(node.attrs?.src ?? "")}"`];
                     if (imgAlt)
                         parts.push(`alt="${escapeAttr(imgAlt)}"`);
diff --git a/packages/mcp/src/lib/markdown-converter.ts b/packages/mcp/src/lib/markdown-converter.ts
index f8753674..25c4d241 100644
--- a/packages/mcp/src/lib/markdown-converter.ts
+++ b/packages/mcp/src/lib/markdown-converter.ts
@@ -233,9 +233,9 @@ export function convertProseMirrorToMarkdown(content: any): string {
         const imgCaption = node.attrs?.caption || "";
         if (imgCaption) {
           // ![]() can't carry a caption, so (symmetric to video) emit a raw
-          // <img> wrapped in a block <div>. markdownToHtml passes it through and
-          // the image extension's parseHTML restores the caption from
-          // data-caption on import.
+          // <img> wrapped in a block <div>. On import marked.parse keeps the raw
+          // HTML and generateJSON runs the image extension's parseHTML, which
+          // restores the caption from data-caption.
           const parts: string[] = [`src="${escapeAttr(node.attrs?.src ?? "")}"`];
           if (imgAlt) parts.push(`alt="${escapeAttr(imgAlt)}"`);
           parts.push(`data-caption="${escapeAttr(imgCaption)}"`);