diff --git a/packages/bubble-core/package.json b/packages/bubble-core/package.json
index 9f699142..4c29cc8b 100644
--- a/packages/bubble-core/package.json
+++ b/packages/bubble-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bubblelab/bubble-core",
-  "version": "0.1.323",
+  "version": "0.1.324",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
diff --git a/packages/bubble-core/src/bubbles/service-bubble/notion/notion.ts b/packages/bubble-core/src/bubbles/service-bubble/notion/notion.ts
index b9e381b7..0c4f705c 100644
--- a/packages/bubble-core/src/bubbles/service-bubble/notion/notion.ts
+++ b/packages/bubble-core/src/bubbles/service-bubble/notion/notion.ts
@@ -335,7 +335,11 @@ const NotionParamsSchema = z.discriminatedUnion('operation', [
     children: z
       .array(z.unknown())
       .optional()
-      .describe('Array of block objects for page content'),
+      .describe(
+        'Array of Notion block objects for page content. Same format as `append_block_children.children`. ' +
+          'For tables, the table block must include `children: [table_row, ...]` inline; ' +
+          "`table_width` must equal every row's cell count."
+      ),
     icon: FileObjectSchema.or(
       z.object({
         type: z.literal('emoji'),
@@ -675,7 +679,21 @@ const NotionParamsSchema = z.discriminatedUnion('operation', [
       .array(z.unknown())
       .min(1)
       .max(100)
-      .describe('Array of block objects to append (max 100)'),
+      .describe(
+        'Array of Notion block objects to append (max 100). ' +
+          'Each block is `{ object: "block", type: "<type>", "<type>": { ... } }`. ' +
+          'Common examples:\n' +
+          '- Paragraph: { object: "block", type: "paragraph", paragraph: { rich_text: [{ type: "text", text: { content: "hello" } }] } }\n' +
+          '- Heading: { object: "block", type: "heading_2", heading_2: { rich_text: [{ type: "text", text: { content: "Title" } }] } }\n' +
+          "- Table (rows MUST be supplied inline as children; table_width must equal every row's cell count): " +
+          '{ object: "block", type: "table", table: { table_width: 2, has_column_header: true, has_row_header: false, ' +
+          'children: [ ' +
+          '{ object: "block", type: "table_row", table_row: { cells: [ [{ type: "text", text: { content: "Name" } }], [{ type: "text", text: { content: "Status" } }] ] } }, ' +
+          '{ object: "block", type: "table_row", table_row: { cells: [ [{ type: "text", text: { content: "Task A" } }], [{ type: "text", text: { content: "Done" } }] ] } } ' +
+          '] } }. ' +
+          'You cannot append rows to an empty table later — always include all rows in the initial create call. ' +
+          'For an empty cell, use `cells: [..., [], ...]` (an empty array) — Notion rejects rich_text items with empty content strings.'
+      ),
     after: z.string().optional().describe('ID of block to append after'),
     credentials: z
       .record(z.nativeEnum(CredentialType), z.string())
diff --git a/packages/bubble-runtime/package.json b/packages/bubble-runtime/package.json
index 6ec1c2fd..7deb8355 100644
--- a/packages/bubble-runtime/package.json
+++ b/packages/bubble-runtime/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bubblelab/bubble-runtime",
-  "version": "0.1.323",
+  "version": "0.1.324",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
diff --git a/packages/bubble-scope-manager/package.json b/packages/bubble-scope-manager/package.json
index d1f0d0a7..a4c2689b 100644
--- a/packages/bubble-scope-manager/package.json
+++ b/packages/bubble-scope-manager/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bubblelab/ts-scope-manager",
-  "version": "0.1.323",
+  "version": "0.1.324",
   "private": false,
   "license": "MIT",
   "type": "commonjs",
diff --git a/packages/bubble-shared-schemas/package.json b/packages/bubble-shared-schemas/package.json
index d1494893..0d4e4819 100644
--- a/packages/bubble-shared-schemas/package.json
+++ b/packages/bubble-shared-schemas/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bubblelab/shared-schemas",
-  "version": "0.1.323",
+  "version": "0.1.324",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
diff --git a/packages/create-bubblelab-app/package.json b/packages/create-bubblelab-app/package.json
index 07093045..c8e55f29 100644
--- a/packages/create-bubblelab-app/package.json
+++ b/packages/create-bubblelab-app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "create-bubblelab-app",
-  "version": "0.1.323",
+  "version": "0.1.324",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Create BubbleLab AI agent applications with one command",
diff --git a/packages/create-bubblelab-app/templates/basic/package.json b/packages/create-bubblelab-app/templates/basic/package.json
index d5f6eb7b..4a7a2432 100644
--- a/packages/create-bubblelab-app/templates/basic/package.json
+++ b/packages/create-bubblelab-app/templates/basic/package.json
@@ -11,9 +11,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bubblelab/bubble-core": "^0.1.323",
-    "@bubblelab/bubble-runtime": "^0.1.323",
-    "@bubblelab/shared-schemas": "^0.1.323",
+    "@bubblelab/bubble-core": "^0.1.324",
+    "@bubblelab/bubble-runtime": "^0.1.324",
+    "@bubblelab/shared-schemas": "^0.1.324",
     "dotenv": "^16.4.5"
   },
   "devDependencies": {
diff --git a/packages/create-bubblelab-app/templates/reddit-scraper/package.json b/packages/create-bubblelab-app/templates/reddit-scraper/package.json
index 3f3fc3c7..23d97439 100644
--- a/packages/create-bubblelab-app/templates/reddit-scraper/package.json
+++ b/packages/create-bubblelab-app/templates/reddit-scraper/package.json
@@ -11,8 +11,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bubblelab/bubble-core": "^0.1.323",
-    "@bubblelab/bubble-runtime": "^0.1.323",
+    "@bubblelab/bubble-core": "^0.1.324",
+    "@bubblelab/bubble-runtime": "^0.1.324",
     "dotenv": "^16.4.5"
   },
   "devDependencies": {