Buffer MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Get aggregated post metrics

get_aggregated_post_metrics

Read-onlyIdempotent

Aggregate post performance for an organization across a date range, optionally filtered by channel or tag.

Instructions

Aggregate post performance for an organization across a date range, optionally filtered by channel or tag. Current Buffer GraphQL aggregatedPostMetrics. One request, no automatic pagination. Use upstream fields to bound data; provider errors are failures even with HTTP 200.

Input Schema

Name	Required	Description
`tags`	No
`fields`	No	Upstream 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.
`account`	No	Private account profile name. Selects credentials only; an organization default does not restrict provider token permissions.
`payload`	No	Complete native input object instead of individual input fields.
`channelIds`	No
`endDateTime`	No
`payload_file`	No	Regular local JSON input file, no symlink, at most 1 MiB; cannot mix with payload or individual input fields.
`startDateTime`	No	Start of the aggregation window. Consumers typically pass UTC midnight of the first calendar day in the window, for example `2026-01-01T00:00:00Z`.
`organizationId`	No	The organization ID

Schema Changelog

Changes observed during successful MCP inspections.

Changed25 schema fields changedv3.0.1Oct 5, 2026

addedInput schema / $defs

Added value: +{
+  "channelIds": {
+    "description": "Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty.",
+    "items": {
+      "description": "Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty.",
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "endDateTime": {
+    "description": "End of the aggregation window. Consumers typically pass UTC midnight of\nthe last calendar day in the window (the backend treats the range as\ninclusive of that day), for example `2026-01-31T00:00:00Z`. Date range\nis capped to 365 days.",
+    "type": "string"
+  },
+  "tags": {
+    "additionalProperties": false,
+    "properties": {
+      "in": {
+        "description": "Include results that have any of the specified tags (union/OR).",
+        "items": {
+          "description": "Include results that have any of the specified tags (union/OR).",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "isEmpty": {
+        "description": "When true, include results that have no tags assigned.\nCan be combined with 'in' for union filtering.\nDefaults to false if not specified.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "in"
+    ],
+    "type": "object"
+  }
+}

addedInput schema / properties / channelIds / $ref
```
Added value: +"#/$defs/channelIds"
```

removedInput schema / properties / channelIds / description

Removed value: -"Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty."

removedInput schema / properties / channelIds / items

Removed value: -{
-  "description": "Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty.",
-  "type": "string"
-}

removedInput schema / properties / channelIds / type
```
Removed value: -"array"
```
addedInput schema / properties / endDateTime / $ref
```
Added value: +"#/$defs/endDateTime"
```

removedInput schema / properties / endDateTime / description

Removed value: -"End of the aggregation window. Consumers typically pass UTC midnight of\nthe last calendar day in the window (the backend treats the range as\ninclusive of that day), for example `2026-01-31T00:00:00Z`. Date range\nis capped to 365 days."

removedInput schema / properties / endDateTime / type
```
Removed value: -"string"
```
addedInput schema / properties / payload / properties / channelIds / $ref
```
Added value: +"#/$defs/channelIds"
```

removedInput schema / properties / payload / properties / channelIds / description

Removed value: -"Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty."

removedInput schema / properties / payload / properties / channelIds / items

Removed value: -{
-  "description": "Optional list of channel IDs to filter by. When omitted (null), the\naggregate spans every channel in the organization the actor has\ninsights access to. When set to an empty array, no channels match and\nthe result is empty.",
-  "type": "string"
-}

removedInput schema / properties / payload / properties / channelIds / type
```
Removed value: -"array"
```
addedInput schema / properties / payload / properties / endDateTime / $ref
```
Added value: +"#/$defs/endDateTime"
```

removedInput schema / properties / payload / properties / endDateTime / description

Removed value: -"End of the aggregation window. Consumers typically pass UTC midnight of\nthe last calendar day in the window (the backend treats the range as\ninclusive of that day), for example `2026-01-31T00:00:00Z`. Date range\nis capped to 365 days."

removedInput schema / properties / payload / properties / endDateTime / type
```
Removed value: -"string"
```
addedInput schema / properties / payload / properties / tags / $ref
```
Added value: +"#/$defs/tags"
```
removedInput schema / properties / payload / properties / tags / additionalProperties
```
Removed value: -false
```

removedInput schema / properties / payload / properties / tags / properties

Removed value: -{
-  "in": {
-    "description": "Include results that have any of the specified tags (union/OR).",
-    "items": {
-      "description": "Include results that have any of the specified tags (union/OR).",
-      "type": "string"
-    },
-    "type": "array"
-  },
-  "isEmpty": {
-    "description": "When true, include results that have no tags assigned.\nCan be combined with 'in' for union filtering.\nDefaults to false if not specified.",
-    "type": "boolean"
-  }
-}

removedInput schema / properties / payload / properties / tags / required
```
Removed value: -[
-  "in"
-]
```
removedInput schema / properties / payload / properties / tags / type
```
Removed value: -"object"
```
addedInput schema / properties / tags / $ref
```
Added value: +"#/$defs/tags"
```
removedInput schema / properties / tags / additionalProperties
```
Removed value: -false
```

removedInput schema / properties / tags / properties

Removed value: -{
-  "in": {
-    "description": "Include results that have any of the specified tags (union/OR).",
-    "items": {
-      "description": "Include results that have any of the specified tags (union/OR).",
-      "type": "string"
-    },
-    "type": "array"
-  },
-  "isEmpty": {
-    "description": "When true, include results that have no tags assigned.\nCan be combined with 'in' for union filtering.\nDefaults to false if not specified.",
-    "type": "boolean"
-  }
-}

removedInput schema / properties / tags / required
```
Removed value: -[
-  "in"
-]
```
removedInput schema / properties / tags / type
```
Removed value: -"object"
```

First observedv2.0.0Oct 3, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral facts beyond that: no automatic pagination, and that provider errors surface as failures even on HTTP 200 — non-obvious traits for an open-world read call.

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

Conciseness4/5

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

Four tight sentences, front-loaded with the core purpose and followed by the operational caveats that matter most. No filler, though the GraphQL-field reference is slightly jargon-dense.

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

Completeness3/5

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

With 9 parameters, nested objects and no output schema, the definition should say more about the aggregate result shape and how to page manually via cursors (only hinted at inside the schema). It covers error and pagination behavior but leaves return-value expectations to inference.

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?

Schema coverage is 67%, below the high-coverage baseline, so the description should carry more weight. It maps to the filter params ('channel or tag') and hints at the fields param ('use upstream fields to bound data'), but says nothing about account, payload, or payload_file, so a third of the surface remains undocumented in both places.

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?

The description names a specific verb+resource ('Aggregate post performance') and adds scope (organization, date range, channel/tag filters), which clearly distinguishes an aggregate-metrics tool from the post-listing siblings like get_posts. It never names a sibling explicitly, so an agent must infer the boundary, keeping it short of a 5.

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?

It gives operational guidance ('Use upstream fields to bound data', 'One request, no automatic pagination', provider errors count as failures), which helps the caller. But it never states when to choose this tool over alternatives such as get_posts or graphql_query, so usage is only implied.

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

Get aggregated post metrics

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools