Skip to main content
Glama
thenavidm

Buffer MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Create content item draft

create_content_item_draft
Destructive

Create a channel-less draft content item with text or assets before choosing channels. Useful for preparing content without network-specific validation.

Instructions

Create a content item holding a channel-less draft, before any channels are selected. No network-specific validation applies to the draft content. The draft needs text or at least one asset.

This API is an early preview and can change without a deprecation period.. Current Buffer GraphQL createContentItemDraft. Requires explicit confirmation. Use upstream fields to bound data; provider errors are failures even with HTTP 200.

Input Schema

NameRequiredDescriptionDefault
draftNo
titleNoOptional title describing what this piece of content is about.
fieldsNoUpstream field paths relative to the result, as in official CLI --fields. Default fields are bounded. Use items.id for connection nodes; pageInfo.endCursor for cursors.
tagIdsNo
accountNoPrivate account profile name. Selects credentials only; an organization default does not restrict provider token permissions.
confirmNoSet true only when the user asked for exactly this action.
payloadNoComplete native input object instead of individual input fields.
targetDateNoOptional date indicating when this piece of content should go out. This is a planning aid only and does not schedule any posts.
payload_fileNoRegular local JSON input file, no symlink, at most 1 MiB; cannot mix with payload or individual input fields.
correlationIdNo
organizationIdNoOrganization that will own the content item.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed26 schema fields changedv3.0.1
    • addedInput schema / $defs
      Added value: +{
+  "correlationId": {
+    "description": "Client-generated UUID that makes draft creation idempotent. A retry with the\nsame UUID in the same organization returns the first content item in its\ncurrent state.",
+    "type": "string"
+  },
+  "draft": {
+    "additionalProperties": false,
+    "properties": {
+      "aiAssisted": {
+        "description": "Set to true when the draft content was written with the help of AI.",
+        "type": "boolean"
+      },
+      "assets": {
+        "description": "Images, videos, or documents to attach to the draft, in display order.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "document": {
+              "additionalProperties": false,
+              "properties": {
+                "thumbnailUrl": {
+                  "description": "Document thumbnail URL",
+                  "type": "string"
+                },
+                "title": {
+                  "description": "Document title",
+                  "type": "string"
+                },
+                "url": {
+                  "description": "Document URL",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "thumbnailUrl",
+                "title",
+                "url"
+              ],
+              "type": "object"
+            },
+            "image": {
+              "additionalProperties": false,
+              "properties": {
+                "metadata": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "altText": {
+                      "description": "Alternative text for accessibility",
+                      "type": "string"
+                    },
+                    "animatedThumbnail": {
+                      "description": "Animated thumbnail URL",
+                      "type": "string"
+                    },
+                    "dimensions": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "height": {
+                          "description": "Image height in pixels",
+                          "type": "integer"
+                        },
+                        "width": {
+                          "description": "Image width in pixels",
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "height",
+                        "width"
+                      ],
+                      "type": "object"
+                    },
+                    "userTags": {
+                      "description": "Accounts to tag at specific points on the image. Each tag's x/y position uses normalized 0.0-1.0 coordinates - see UserTagInput.",
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "handle": {
+                            "description": "The handle (username) of the account to tag, without the leading @.",
+                            "type": "string"
+                          },
+                          "x": {
+                            "description": "Horizontal position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image width from the left edge (0.5 is the horizontal center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel X by the image width.",
+                            "type": "number"
+                          },
+                          "y": {
+                            "description": "Vertical position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image height from the top edge (0.5 is the vertical center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel Y by the image height.",
+                            "type": "number"
+                          }
+                        },
+                        "required": [
+                          "handle",
+                          "x",
+                          "y"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "altText"
+                  ],
+                  "type": "object"
+                },
+                "thumbnailUrl": {
+                  "description": "URL to the static thumbnail of the asset",
+                  "type": "string"
+                },
+                "url": {
+                  "description": "URL to the file source",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "type": "object"
+            },
+            "link": {
+              "additionalProperties": false,
+              "properties": {
+                "description": {
+                  "description": "Description of the link",
+                  "type": "string"
+                },
+                "thumbnailUrl": {
+                  "description": "Thumbnail URL of the link",
+                  "type": "string"
+                },
+                "title": {
+                  "description": "Title of the link",
+                  "type": "string"
+                },
+                "url": {
+                  "description": "URL to the link",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "type": "object"
+            },
+            "video": {
+              "additionalProperties": false,
+              "properties": {
+                "metadata": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "thumbnailOffset": {
+                      "description": "Offset of the thumbnail chosen for the video, in ms",
+                      "type": "integer"
+                    },
+                    "title": {
+                      "description": "Video title",
+                      "type": "string"
+                    }
+                  },
+                  "required": [],
+                  "type": "object"
+                },
+                "thumbnailUrl": {
+                  "description": "Do not use: social networks do not accept custom video thumbnail images, and\nthe API rejects video assets that set this field. To choose the video\nthumbnail, set `metadata.thumbnailOffset` to select a frame from the video\n(supported for Instagram, TikTok, and Pinterest only).",
+                  "type": "string"
+                },
+                "url": {
+                  "description": "URL to the file source",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "text": {
+        "description": "The written content of the draft. Can be empty when the draft holds at\nleast one asset.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "text"
+    ],
+    "type": "object"
+  },
+  "tagIds": {
+    "description": "Tags to apply to this content item. Omit to create it with no tags.",
+    "items": {
+      "description": "Tags to apply to this content item. Omit to create it with no tags.",
+      "type": "string"
+    },
+    "type": "array"
+  }
+}
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true for this exact user-requested Buffer mutation."New value: +"Set true only when the user asked for exactly this action."
    • addedInput schema / properties / correlationId / $ref
      Added value: +"#/$defs/correlationId"
    • removedInput schema / properties / correlationId / description
      Removed value: -"Client-generated UUID that makes draft creation idempotent. A retry with the\nsame UUID in the same organization returns the first content item in its\ncurrent state."
    • removedInput schema / properties / correlationId / type
      Removed value: -"string"
    • addedInput schema / properties / draft / $ref
      Added value: +"#/$defs/draft"
    • removedInput schema / properties / draft / additionalProperties
      Removed value: -false
    • removedInput schema / properties / draft / properties
      Removed value: -{
-  "aiAssisted": {
-    "description": "Set to true when the draft content was written with the help of AI.",
-    "type": "boolean"
-  },
-  "assets": {
-    "description": "Images, videos, or documents to attach to the draft, in display order.",
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "document": {
-          "additionalProperties": false,
-          "properties": {
-            "thumbnailUrl": {
-              "description": "Document thumbnail URL",
-              "type": "string"
-            },
-            "title": {
-              "description": "Document title",
-              "type": "string"
-            },
-            "url": {
-              "description": "Document URL",
-              "type": "string"
-            }
-          },
-          "required": [
-            "thumbnailUrl",
-            "title",
-            "url"
-          ],
-          "type": "object"
-        },
-        "image": {
-          "additionalProperties": false,
-          "properties": {
-            "metadata": {
-              "additionalProperties": false,
-              "properties": {
-                "altText": {
-                  "description": "Alternative text for accessibility",
-                  "type": "string"
-                },
-                "animatedThumbnail": {
-                  "description": "Animated thumbnail URL",
-                  "type": "string"
-                },
-                "dimensions": {
-                  "additionalProperties": false,
-                  "properties": {
-                    "height": {
-                      "description": "Image height in pixels",
-                      "type": "integer"
-                    },
-                    "width": {
-                      "description": "Image width in pixels",
-                      "type": "integer"
-                    }
-                  },
-                  "required": [
-                    "height",
-                    "width"
-                  ],
-                  "type": "object"
-                },
-                "userTags": {
-                  "description": "Accounts to tag at specific points on the image. Each tag's x/y position uses normalized 0.0-1.0 coordinates - see UserTagInput.",
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "handle": {
-                        "description": "The handle (username) of the account to tag, without the leading @.",
-                        "type": "string"
-                      },
-                      "x": {
-                        "description": "Horizontal position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image width from the left edge (0.5 is the horizontal center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel X by the image width.",
-                        "type": "number"
-                      },
-                      "y": {
-                        "description": "Vertical position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image height from the top edge (0.5 is the vertical center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel Y by the image height.",
-                        "type": "number"
-                      }
-                    },
-                    "required": [
-                      "handle",
-                      "x",
-                      "y"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                }
-              },
-              "required": [
-                "altText"
-              ],
-              "type": "object"
-            },
-            "thumbnailUrl": {
-              "description": "URL to the static thumbnail of the asset",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the file source",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        },
-        "link": {
-          "additionalProperties": false,
-          "properties": {
-            "description": {
-              "description": "Description of the link",
-              "type": "string"
-            },
-            "thumbnailUrl": {
-              "description": "Thumbnail URL of the link",
-              "type": "string"
-            },
-            "title": {
-              "description": "Title of the link",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the link",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        },
-        "video": {
-          "additionalProperties": false,
-          "properties": {
-            "metadata": {
-              "additionalProperties": false,
-              "properties": {
-                "thumbnailOffset": {
-                  "description": "Offset of the thumbnail chosen for the video, in ms",
-                  "type": "integer"
-                },
-                "title": {
-                  "description": "Video title",
-                  "type": "string"
-                }
-              },
-              "required": [],
-              "type": "object"
-            },
-            "thumbnailUrl": {
-              "description": "Do not use: social networks do not accept custom video thumbnail images, and\nthe API rejects video assets that set this field. To choose the video\nthumbnail, set `metadata.thumbnailOffset` to select a frame from the video\n(supported for Instagram, TikTok, and Pinterest only).",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the file source",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        }
-      },
-      "required": [],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "text": {
-    "description": "The written content of the draft. Can be empty when the draft holds at\nleast one asset.",
-    "type": "string"
-  }
-}
    • removedInput schema / properties / draft / required
      Removed value: -[
-  "text"
-]
    • removedInput schema / properties / draft / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / correlationId / $ref
      Added value: +"#/$defs/correlationId"
    • removedInput schema / properties / payload / properties / correlationId / description
      Removed value: -"Client-generated UUID that makes draft creation idempotent. A retry with the\nsame UUID in the same organization returns the first content item in its\ncurrent state."
    • removedInput schema / properties / payload / properties / correlationId / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / draft / $ref
      Added value: +"#/$defs/draft"
    • removedInput schema / properties / payload / properties / draft / additionalProperties
      Removed value: -false
    • removedInput schema / properties / payload / properties / draft / properties
      Removed value: -{
-  "aiAssisted": {
-    "description": "Set to true when the draft content was written with the help of AI.",
-    "type": "boolean"
-  },
-  "assets": {
-    "description": "Images, videos, or documents to attach to the draft, in display order.",
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "document": {
-          "additionalProperties": false,
-          "properties": {
-            "thumbnailUrl": {
-              "description": "Document thumbnail URL",
-              "type": "string"
-            },
-            "title": {
-              "description": "Document title",
-              "type": "string"
-            },
-            "url": {
-              "description": "Document URL",
-              "type": "string"
-            }
-          },
-          "required": [
-            "thumbnailUrl",
-            "title",
-            "url"
-          ],
-          "type": "object"
-        },
-        "image": {
-          "additionalProperties": false,
-          "properties": {
-            "metadata": {
-              "additionalProperties": false,
-              "properties": {
-                "altText": {
-                  "description": "Alternative text for accessibility",
-                  "type": "string"
-                },
-                "animatedThumbnail": {
-                  "description": "Animated thumbnail URL",
-                  "type": "string"
-                },
-                "dimensions": {
-                  "additionalProperties": false,
-                  "properties": {
-                    "height": {
-                      "description": "Image height in pixels",
-                      "type": "integer"
-                    },
-                    "width": {
-                      "description": "Image width in pixels",
-                      "type": "integer"
-                    }
-                  },
-                  "required": [
-                    "height",
-                    "width"
-                  ],
-                  "type": "object"
-                },
-                "userTags": {
-                  "description": "Accounts to tag at specific points on the image. Each tag's x/y position uses normalized 0.0-1.0 coordinates - see UserTagInput.",
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "handle": {
-                        "description": "The handle (username) of the account to tag, without the leading @.",
-                        "type": "string"
-                      },
-                      "x": {
-                        "description": "Horizontal position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image width from the left edge (0.5 is the horizontal center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel X by the image width.",
-                        "type": "number"
-                      },
-                      "y": {
-                        "description": "Vertical position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image height from the top edge (0.5 is the vertical center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel Y by the image height.",
-                        "type": "number"
-                      }
-                    },
-                    "required": [
-                      "handle",
-                      "x",
-                      "y"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                }
-              },
-              "required": [
-                "altText"
-              ],
-              "type": "object"
-            },
-            "thumbnailUrl": {
-              "description": "URL to the static thumbnail of the asset",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the file source",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        },
-        "link": {
-          "additionalProperties": false,
-          "properties": {
-            "description": {
-              "description": "Description of the link",
-              "type": "string"
-            },
-            "thumbnailUrl": {
-              "description": "Thumbnail URL of the link",
-              "type": "string"
-            },
-            "title": {
-              "description": "Title of the link",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the link",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        },
-        "video": {
-          "additionalProperties": false,
-          "properties": {
-            "metadata": {
-              "additionalProperties": false,
-              "properties": {
-                "thumbnailOffset": {
-                  "description": "Offset of the thumbnail chosen for the video, in ms",
-                  "type": "integer"
-                },
-                "title": {
-                  "description": "Video title",
-                  "type": "string"
-                }
-              },
-              "required": [],
-              "type": "object"
-            },
-            "thumbnailUrl": {
-              "description": "Do not use: social networks do not accept custom video thumbnail images, and\nthe API rejects video assets that set this field. To choose the video\nthumbnail, set `metadata.thumbnailOffset` to select a frame from the video\n(supported for Instagram, TikTok, and Pinterest only).",
-              "type": "string"
-            },
-            "url": {
-              "description": "URL to the file source",
-              "type": "string"
-            }
-          },
-          "required": [
-            "url"
-          ],
-          "type": "object"
-        }
-      },
-      "required": [],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "text": {
-    "description": "The written content of the draft. Can be empty when the draft holds at\nleast one asset.",
-    "type": "string"
-  }
-}
    • removedInput schema / properties / payload / properties / draft / required
      Removed value: -[
-  "text"
-]
    • removedInput schema / properties / payload / properties / draft / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / tagIds / $ref
      Added value: +"#/$defs/tagIds"
    • removedInput schema / properties / payload / properties / tagIds / description
      Removed value: -"Tags to apply to this content item. Omit to create it with no tags."
    • removedInput schema / properties / payload / properties / tagIds / items
      Removed value: -{
-  "description": "Tags to apply to this content item. Omit to create it with no tags.",
-  "type": "string"
-}
    • removedInput schema / properties / payload / properties / tagIds / type
      Removed value: -"array"
    • addedInput schema / properties / tagIds / $ref
      Added value: +"#/$defs/tagIds"
    • removedInput schema / properties / tagIds / description
      Removed value: -"Tags to apply to this content item. Omit to create it with no tags."
    • removedInput schema / properties / tagIds / items
      Removed value: -{
-  "description": "Tags to apply to this content item. Omit to create it with no tags.",
-  "type": "string"
-}
    • removedInput schema / properties / tagIds / type
      Removed value: -"array"
  2. First observedv2.0.0

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds context the annotations cannot convey: that the endpoint is an early preview that can change without deprecation notice, that no network-specific validation applies, that explicit confirmation is required, and that provider errors surface as failures even on HTTP 200. It does not explain the destructiveHint=true implication for a create operation, which would have been valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and sentences are individually dense, but the tail is a choppy wall of unrelated operational notes ('Current Buffer GraphQL createContentItemDraft. Requires explicit confirmation. Use upstream fields...') and there is a stray double period after 'deprecation period'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter nested mutation with no output schema, the description covers the key invariants (draft content requirement, confirmation gate, preview instability, error semantics). It omits only the payload/payload_file mutual exclusion and return-shape expectations, which the schema largely handles.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 73% schema coverage and 11 parameters, the schema does most of the work. The description adds only the draft-content invariant (text or at least one asset) and a hint about the fields parameter; correlationId idempotency, organizationId, account, payload vs payload_file exclusivity, and targetDate are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (create a content item) plus the distinguishing scope: a channel-less draft created before any channels are selected. That implicitly separates it from create_content_item and create_post, though it never names a sibling to route the agent explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real preconditions ('before any channels are selected', 'needs text or at least one asset') and a confirmation requirement, plus 'use upstream fields to bound data'. It still never says when to prefer this over create_content_item, promote_content_item_draft_to_posts, or update_content_item_draft.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools