fix(buffer): format nested input documentation

Author: waleedlatif1

apps/docs/content/docs/integrations/buffer.mdx

@@ -72,13 +72,19 @@ export const bufferCreateIdeaTool: ToolConfig<BufferCreateIdeaParams, BufferIdea
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('IdeaContentInput'),
+      description: bufferInputDescription(
+        'IdeaContentInput',
+        'Idea title, text, and media content.'
+      ),
     },
     group: {
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('IdeaGroupInput'),
+      description: bufferInputDescription(
+        'IdeaGroupInput',
+        'Assign the idea to a group and optionally position it after another idea.'
+      ),
     },
     cta: {
       type: 'string',

apps/sim/tools/buffer/create_idea.ts

@@ -85,13 +85,19 @@ export const bufferCreatePostTool: InternalToolConfig<BufferCreatePostParams, Bu
         type: 'json',
         required: false,
         visibility: 'user-or-llm',
-        description: `Array of assets: ${bufferInputDescription('AssetInput')}. Choose exactly one variant per asset. Omit when using media. On edit, [] clears attachments and omission preserves them.`,
+        description: bufferInputDescription(
+          'AssetInput',
+          'Array of image, video, or document assets. Choose exactly one variant per asset. Omit when using media.'
+        ),
       },
       metadata: {
         type: 'json',
         required: false,
         visibility: 'user-or-llm',
-        description: bufferInputDescription('PostInputMetaData'),
+        description: bufferInputDescription(
+          'PostInputMetaData',
+          'Network-specific settings, including threads, link attachments, and publishing options.'
+        ),
       },
       aiAssisted: {
         type: 'boolean',

apps/sim/tools/buffer/create_post.ts

@@ -83,13 +83,19 @@ export const bufferEditPostTool: InternalToolConfig<BufferEditPostParams, Buffer
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: `Array of assets: ${bufferInputDescription('AssetInput')}. Choose exactly one variant per asset. Omit when using media. On edit, [] clears attachments and omission preserves them.`,
+      description: bufferInputDescription(
+        'AssetInput',
+        'Array of image, video, or document assets. Choose exactly one variant per asset. Omit when using media. An empty array clears attachments; omission preserves them.'
+      ),
     },
     metadata: {
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('PostInputMetaData'),
+      description: bufferInputDescription(
+        'PostInputMetaData',
+        'Network-specific settings, including threads, link attachments, and publishing options.'
+      ),
     },
     aiAssisted: {
       type: 'boolean',

apps/sim/tools/buffer/edit_post.ts

@@ -60,7 +60,10 @@ export const bufferGetAggregatedPostMetricsTool: ToolConfig<
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('TagComparator'),
+      description: bufferInputDescription(
+        'TagComparator',
+        'Filter metrics by tag IDs or untagged status.'
+      ),
     },
   },
   request: {

apps/sim/tools/buffer/get-aggregated-post-metrics.ts

@@ -32,7 +32,10 @@ export const bufferGetAccountTool: ToolConfig<BufferGetAccountParams, BufferAcco
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('OrganizationFilterInput'),
+      description: bufferInputDescription(
+        'OrganizationFilterInput',
+        'Filter account organizations by organization ID.'
+      ),
     },
   },
 

apps/sim/tools/buffer/get_account.ts

@@ -43,7 +43,10 @@ export const bufferGetChannelsTool: ToolConfig<BufferGetChannelsParams, BufferCh
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('ChannelsFiltersInput'),
+      description: bufferInputDescription(
+        'ChannelsFiltersInput',
+        'Filter channels by locked status or product.'
+      ),
     },
   },
 

apps/sim/tools/buffer/get_channels.ts

@@ -67,13 +67,16 @@ export const bufferGetIdeasTool: ToolConfig<BufferGetIdeasParams, BufferIdeasRes
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('IdeasGroupFilter'),
+      description: bufferInputDescription('IdeasGroupFilter', 'Filter ideas by group.'),
     },
     tagsFilter: {
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('TagComparator'),
+      description: bufferInputDescription(
+        'TagComparator',
+        'Filter ideas by tag IDs or untagged status.'
+      ),
     },
   },
 

apps/sim/tools/buffer/get_ideas.ts

@@ -104,13 +104,19 @@ export const bufferGetPostsTool: ToolConfig<BufferGetPostsParams, BufferPostsRes
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: bufferInputDescription('PostsFiltersInput'),
+      description: bufferInputDescription(
+        'PostsFiltersInput',
+        'Filter posts by status, tags, dates, and other criteria.'
+      ),
     },
     sort: {
       type: 'json',
       required: false,
       visibility: 'user-or-llm',
-      description: `Ordered list of sort keys: ${bufferInputDescription('PostSortInput')}. Overrides sortBy/sortDirection.`,
+      description: bufferInputDescription(
+        'PostSortInput',
+        'Ordered array of sort keys. Overrides sortBy and sortDirection.'
+      ),
     },
   },
 

apps/sim/tools/buffer/get_posts.ts

@@ -171,17 +171,34 @@ export function parseBufferInput(
   return result
 }
 
-/** Lists the complete nested input contract for structured tool parameters. */
-export function bufferInputDescription(type: string): string {
-  const schema = BUFFER_SCHEMA[type]
-  if (!schema?.fields) return schema?.values?.join(' | ') ?? type
-  return `{ ${Object.entries(schema.fields)
-    .map(([field, wireType]) => {
-      const nested = baseType(wireType)
-      const detail = BUFFER_SCHEMA[nested]
-      return `${field}: ${wireType}${schema.defaults?.includes(field) ? ' (provider default when omitted)' : ''}${detail?.fields || detail?.values ? ` (${bufferInputDescription(nested)})` : ''}`
-    })
-    .join('; ')} }`
+/** Describes structured inputs with a readable definition for each referenced type. */
+export function bufferInputDescription(type: string, description: string): string {
+  const definitions: string[] = []
+  const visited = new Set<string>()
+
+  function collect(name: string): void {
+    const schema = BUFFER_SCHEMA[name]
+    if (visited.has(name) || (!schema?.fields && !schema?.values)) return
+    visited.add(name)
+    if (schema.fields) {
+      const fields = Object.entries(schema.fields).map(
+        ([field, wireType]) =>
+          `  ${field}: ${wireType}${schema.defaults?.includes(field) ? ' # Provider default when omitted' : ''}`
+      )
+      if (schema.oneOf) fields.unshift('  # Choose exactly one field')
+      definitions.push(`input ${name} {\n${fields.join('\n')}\n}`)
+      for (const wireType of Object.values(schema.fields)) collect(baseType(wireType))
+    } else if (schema.values) {
+      definitions.push(
+        `enum ${name} {\n${schema.values.map((value) => `  ${value}`).join('\n')}\n}`
+      )
+    }
+  }
+
+  collect(type)
+  return definitions.length
+    ? `${description}\n\n\`\`\`graphql\n${definitions.join('\n\n')}\n\`\`\``
+    : description
 }
 
 function parseValue(wireType: string, value: unknown, path: string): unknown {