@@ -335,7 +335,11 @@ const NotionParamsSchema = z.discriminatedUnion('operation', [
335335 children : z
336336 . array ( z . unknown ( ) )
337337 . optional ( )
338- . describe ( 'Array of block objects for page content' ) ,
338+ . describe (
339+ 'Array of Notion block objects for page content. Same format as `append_block_children.children`. ' +
340+ 'For tables, the table block must include `children: [table_row, ...]` inline; ' +
341+ "`table_width` must equal every row's cell count."
342+ ) ,
339343 icon : FileObjectSchema . or (
340344 z . object ( {
341345 type : z . literal ( 'emoji' ) ,
@@ -675,7 +679,21 @@ const NotionParamsSchema = z.discriminatedUnion('operation', [
675679 . array ( z . unknown ( ) )
676680 . min ( 1 )
677681 . max ( 100 )
678- . describe ( 'Array of block objects to append (max 100)' ) ,
682+ . describe (
683+ 'Array of Notion block objects to append (max 100). ' +
684+ 'Each block is `{ object: "block", type: "<type>", "<type>": { ... } }`. ' +
685+ 'Common examples:\n' +
686+ '- Paragraph: { object: "block", type: "paragraph", paragraph: { rich_text: [{ type: "text", text: { content: "hello" } }] } }\n' +
687+ '- Heading: { object: "block", type: "heading_2", heading_2: { rich_text: [{ type: "text", text: { content: "Title" } }] } }\n' +
688+ "- Table (rows MUST be supplied inline as children; table_width must equal every row's cell count): " +
689+ '{ object: "block", type: "table", table: { table_width: 2, has_column_header: true, has_row_header: false, ' +
690+ 'children: [ ' +
691+ '{ object: "block", type: "table_row", table_row: { cells: [ [{ type: "text", text: { content: "Name" } }], [{ type: "text", text: { content: "Status" } }] ] } }, ' +
692+ '{ object: "block", type: "table_row", table_row: { cells: [ [{ type: "text", text: { content: "Task A" } }], [{ type: "text", text: { content: "Done" } }] ] } } ' +
693+ '] } }. ' +
694+ 'You cannot append rows to an empty table later — always include all rows in the initial create call. ' +
695+ 'For an empty cell, use `cells: [..., [], ...]` (an empty array) — Notion rejects rich_text items with empty content strings.'
696+ ) ,
679697 after : z . string ( ) . optional ( ) . describe ( 'ID of block to append after' ) ,
680698 credentials : z
681699 . record ( z . nativeEnum ( CredentialType ) , z . string ( ) )
0 commit comments