posterly-mcp-server 0.48.5 → 0.49.0

package/src/lib/format.ts

@@ -1,4 +1,4 @@
-import type { Account, LearnedVoice, Post } from './api-client.js';
+import type { Account, LearnedVoice, ListPostsResponse, Post, PostCountsResponse, PostsRangeEcho } from './api-client.js';
 
 type CellValue = string | number | boolean | null | undefined;
 
@@ -244,3 +244,203 @@ function isInCurrentMonth(value?: string | null): boolean {
   const now = new Date();
   return date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth();
 }
+
+/**
+ * The completeness line every paged list prints, so an agent always knows
+ * whether it has seen everything. Shared by the npm package and the hosted
+ * endpoint.
+ */
+export function formatPagingNote(input: {
+  noun: string;
+  tool: string;
+  offset?: number | null;
+  count: number;
+  total?: number | null;
+  hasMore: boolean;
+  nextOffset?: number | null;
+}): string {
+  const offset = input.offset ?? 0;
+  const first = offset + 1;
+  const last = offset + input.count;
+  const ofTotal = typeof input.total === 'number' ? ` of ${input.total}` : '';
+  if (input.hasMore) {
+    const next = typeof input.nextOffset === 'number' ? input.nextOffset : last;
+    return `**Not complete: showing ${first}-${last}${ofTotal} ${input.noun}.** More available: call ${input.tool} again with the same filters and offset=${next}. Keep paging until this says complete before drawing any conclusion about totals.`;
+  }
+  if (offset === 0) {
+    return `**Complete: all ${typeof input.total === 'number' ? input.total : input.count} ${input.noun} are shown.**`;
+  }
+  return `**Complete: this is the last page (${input.noun} ${first}-${last}${ofTotal}).**`;
+}
+
+// ---------------------------------------------------------------------------
+// list_posts: shared by the npm package and the hosted endpoint
+// (lib/mcp/http-tools.ts imports these), so both surfaces print the same
+// completeness line and the same times for the same response.
+// ---------------------------------------------------------------------------
+
+export type PostListRange = PostsRangeEcho;
+export type PostListPage = ListPostsResponse;
+export type { PostCountsResponse };
+
+function zonedParts(value: string | Date, timeZone: string): Record<string, string> {
+  const date = typeof value === 'string' ? new Date(value) : value;
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(date);
+  return Object.fromEntries(parts.map((part) => [part.type, part.value]));
+}
+
+/** "Wed, Oct 1, 2026, 09:00" in `timeZone`; the raw value when it is not a date. */
+export function formatDateTimeInZone(value: string | null | undefined, timeZone: string): string {
+  if (!value) return 'not scheduled';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  const p = zonedParts(date, timeZone);
+  return `${p.weekday}, ${p.month} ${p.day}, ${p.year}, ${p.hour}:${p.minute}`;
+}
+
+/** "Wed, Oct 1, 2026" for a YYYY-MM-DD calendar day. */
+export function formatCalendarDay(day: string): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+  if (!match) return day;
+  const p = zonedParts(new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12)), 'UTC');
+  return `${p.weekday}, ${p.month} ${p.day}, ${p.year}`;
+}
+
+function isZonedMidnight(value: string, timeZone: string): boolean {
+  const p = zonedParts(value, timeZone);
+  return p.hour === '00' && p.minute === '00' && p.second === '00';
+}
+
+function zonedDay(value: string | Date, timeZone: string): string {
+  const p = zonedParts(value, timeZone);
+  return `${p.month} ${p.day}, ${p.year}`;
+}
+
+/**
+ * The scheduled range in plain words. Whole days read as "Oct 1, 2026 to
+ * Oct 31, 2026" (the API's `to` is exclusive, so a midnight `to` ends the
+ * day before); anything else reads as "from X up to Y".
+ */
+export function formatPostRange(range: PostListRange): string {
+  const tz = range.timezone;
+  if (range.from && range.to && isZonedMidnight(range.from, tz) && isZonedMidnight(range.to, tz)) {
+    const lastDay = new Date(Date.parse(range.to) - 1);
+    return `${zonedDay(range.from, tz)} to ${zonedDay(lastDay, tz)} (${tz})`;
+  }
+  const from = range.from ? `from ${formatDateTimeInZone(range.from, tz)}` : '';
+  const to = range.to ? `up to ${formatDateTimeInZone(range.to, tz)}` : '';
+  return `${[from, to].filter(Boolean).join(' ')} (${tz})`;
+}
+
+function approvalCell(post: Post): string {
+  if (!post.approval || post.approval.status === 'none') return 'none';
+  return post.approval.waiting_on ? `${post.approval.status} (waiting on ${post.approval.waiting_on})` : post.approval.status;
+}
+
+/**
+ * One page of list_posts. Always says whether every matching post is shown,
+ * and when it is not, exactly which offset to call next, so an agent never
+ * mistakes the first page for the whole schedule.
+ */
+export function formatPostListPage(
+  data: PostListPage,
+  options: { timeZone: string; dashboardUrl?: string },
+): string {
+  const posts = Array.isArray(data.posts) ? data.posts : [];
+  const total = typeof data.total === 'number' ? data.total : posts.length;
+  const offset = typeof data.offset === 'number' ? data.offset : 0;
+  const tz = options.timeZone;
+  const rangeLine = data.range ? `Scheduled ${formatPostRange(data.range)}` : '';
+  const orderLine = data.order === 'asc' ? 'oldest first' : 'newest first';
+
+  if (posts.length === 0) {
+    const detail = total > 0
+      ? `No posts on this page: offset ${offset} is past the last of the ${total} matching posts. Call again with a lower offset.`
+      : `No posts match these filters${data.range ? ` (${formatPostRange(data.range)})` : ''}. This is complete: there is nothing more to page through.`;
+    return [
+      mdTitle('No posts'),
+      detail,
+      '\n**Next step for the AI agent:** tell the user nothing matches that filter, then ask what they want to schedule next.',
+    ].join('\n');
+  }
+
+  const first = offset + 1;
+  const last = offset + posts.length;
+  const hasMore = typeof data.has_more === 'boolean' ? data.has_more : last < total;
+  const nextOffset = typeof data.next_offset === 'number' ? data.next_offset : last;
+  const completeness = hasMore
+    ? `**Not complete: showing ${first}-${last} of ${total} matching posts.** More available: call list_posts again with the same filters and offset=${nextOffset}. Keep paging until every post is shown before drawing any conclusion about totals, gaps, or how busy a day or client is. For "how many" questions, use view=counts.`
+    : first === 1
+      ? `**Complete: all ${total} matching posts are shown.**`
+      : `**Complete: this is the last page (posts ${first}-${last} of ${total}).**`;
+
+  const table = mdTable(
+    ['Status', 'Post ID', `Scheduled (${tz})`, 'Type', 'Account ID', 'Brand ID', 'Approval', 'Caption'],
+    // The API post row carries account and brand IDs only (no joined names);
+    // list_accounts and list_brands, or view=counts, resolve them.
+    posts.map((post) => [
+      statusLabel(post.status),
+      code(String(post.id)),
+      formatDateTimeInZone(post.scheduled_at, tz),
+      post.post_type || 'post',
+      post.social_account_id != null ? String(post.social_account_id) : 'n/a',
+      post.brand_id || 'none',
+      approvalCell(post),
+      compactText(post.content, 80) || '(empty)',
+    ]),
+  );
+
+  return [
+    mdTitle(
+      hasMore || first > 1 ? `Posts ${first}-${last} of ${total}` : `Posts (${total})`,
+      [rangeLine, orderLine, `times in ${tz}`].filter(Boolean).join(' · '),
+    ),
+    table,
+    completeness,
+    options.dashboardUrl ? `View in posterly: ${options.dashboardUrl}` : '',
+  ].filter(Boolean).join('\n\n');
+}
+
+/** The counts view of list_posts: exact totals per day, status, account, and brand. */
+export function formatPostCounts(data: PostCountsResponse): string {
+  const range = data.range;
+  const days = Array.isArray(data.by_day) ? data.by_day : [];
+  const emptyDays = days.filter((day) => day.count === 0).map((day) => formatCalendarDay(day.date));
+  const sections = [
+    mdTitle(`Post counts: ${data.total} ${data.total === 1 ? 'post' : 'posts'}`, range ? formatPostRange(range) : undefined),
+    data.truncated
+      ? `**Partial grouping:** ${data.total} posts match, but only the first ${data.counted} were grouped below. The total is exact; narrow the range or filters for exact per-day numbers.`
+      : `**Complete:** every one of the ${data.total} matching posts is counted below.`,
+    mdSection('By day', mdTable(['Day', 'Posts'], days.map((day) => [formatCalendarDay(day.date), day.count]))),
+    // A truncated grouping only covers the earliest posts, so a day with a
+    // zero here may still have posts: never list "empty" days then.
+    days.length > 0 && !data.truncated ? `Days with no posts: ${emptyDays.length > 0 ? emptyDays.join('; ') : 'none'}.` : '',
+    data.truncated ? '_Per-day numbers above cover only the grouped posts, so a day showing 0 may still have posts. Narrow the range to check for empty days._' : '',
+    mdSection('By status', mdTable(['Status', 'Posts'], (data.by_status || []).map((row) => [statusLabel(row.status), row.count]))),
+    mdSection('By account', mdTable(
+      ['Account', 'Platform', 'Account ID', 'Posts'],
+      (data.by_account || []).map((row) => [
+        row.username ? `@${row.username}` : row.account_id ? 'unknown account' : 'no account',
+        row.platform || 'n/a',
+        row.account_id ?? 'none',
+        row.count,
+      ]),
+    )),
+    mdSection('By brand', mdTable(
+      ['Brand', 'Brand ID', 'Posts'],
+      (data.by_brand || []).map((row) => [row.name || (row.brand_id ? 'unknown brand' : 'no brand'), row.brand_id ?? 'none', row.count]),
+    )),
+    '**Next step for the AI agent:** these totals are exact for the filters above. To read the posts themselves, call list_posts with view=list and the same filters, paging with offset until every post is shown.',
+  ];
+  return sections.filter(Boolean).join('\n\n');
+}

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.48.5';
+export const POSTERLY_MCP_VERSION = '0.49.0';

package/src/tools/get-updates.ts

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { formatPagingNote } from '../lib/format.js';
 
 export const getUpdatesTool = {
   name: 'get_updates',
   description:
-    'Get the latest posterly product updates and news from the updates feed: new features, improvements, and fixes. Requires an active posterly subscription.',
+    'Get the latest posterly product updates and news from the updates feed: new features, improvements, and fixes, newest first. The output says whether more updates exist; page with offset or narrow with since. Requires an active posterly subscription.',
   inputSchema: z.object({
     limit: z.number().int().min(1).max(50).optional().describe('Number of updates to return. Default 10, max 50.'),
+    offset: z.number().int().min(0).optional().describe('How many updates to skip. Use the offset the previous page gives to get the next page.'),
     since: z.string().optional().describe('ISO date. Return updates published on or after this date.'),
     include_content: z.boolean().optional().describe('Include the full markdown body of each update. Defaults to false.'),
   }),
@@ -15,6 +17,7 @@ export const getUpdatesTool = {
     client: PosterlyClient,
     input: {
       limit?: number;
+      offset?: number;
       since?: string;
       include_content?: boolean;
     },
@@ -36,6 +39,17 @@ export const getUpdatesTool = {
       }
     }
 
+    lines.push('', formatPagingNote({
+      noun: 'updates',
+      tool: 'get_updates',
+      offset: result.offset ?? input.offset ?? 0,
+      count: result.updates.length,
+      total: result.total,
+      // An API older than has_more: a full page may mean more exist.
+      hasMore: result.has_more ?? result.updates.length >= (input.limit || 10),
+      nextOffset: result.next_offset,
+    }));
+
     return lines.join('\n');
   },
 };

package/src/tools/list-activity.ts

@@ -1,16 +1,18 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { formatPagingNote } from '../lib/format.js';
 
 export const listActivityTool = {
   name: 'list_activity',
   description:
-    'List recent activity and publish events for posts, including status changes, publish attempts, failures, and retries. Use this as the agent notifications feed.',
+    'List recent activity and publish events for posts, including status changes, publish attempts, failures, and retries, newest first. Use this as the agent notifications feed. The output says whether more events exist; page with offset (offset + limit up to 1000) or narrow with since or post_id before concluding nothing else happened.',
   inputSchema: z.object({
     workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
     post_id: z.number().int().positive().optional().describe('Filter to one post ID.'),
     since: z.string().optional().describe('ISO datetime. Return events created at or after this time.'),
     type: z.enum(['all', 'activity', 'publish']).optional().describe('Event source filter. Defaults to all.'),
     limit: z.number().int().min(1).max(100).optional().describe('Number of items to return. Default 50, max 100.'),
+    offset: z.number().int().min(0).optional().describe('How many events to skip. Use the offset the previous page gives to get the next page.'),
   }),
 
   async execute(
@@ -21,15 +23,18 @@ export const listActivityTool = {
       since?: string;
       type?: 'all' | 'activity' | 'publish';
       limit?: number;
+      offset?: number;
     },
   ) {
     const result = await client.listActivity(input);
     if (result.items.length === 0) {
-      return 'No activity found matching your filters.';
+      return (input.offset ?? 0) > 0
+        ? `No activity on this page: offset ${input.offset} is past the last matching event.`
+        : 'No activity found matching your filters.';
     }
 
     const lines = [
-      `Activity (${result.items.length} of ${result.total}):`,
+      `Activity (${result.items.length} on this page):`,
     ];
 
     for (const item of result.items) {
@@ -45,6 +50,16 @@ export const listActivityTool = {
       }
     }
 
+    lines.push('', formatPagingNote({
+      noun: 'events',
+      tool: 'list_activity',
+      offset: result.offset ?? input.offset ?? 0,
+      count: result.items.length,
+      // An API older than has_more: a full page may mean more exist.
+      hasMore: result.has_more ?? result.items.length >= (result.limit || 50),
+      nextOffset: result.next_offset,
+    }));
+
     return lines.join('\n');
   },
 };

package/src/tools/list-media.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { formatPagingNote } from '../lib/format.js';
 
 export const listMediaTool = {
   name: 'list_media',
   description:
-    'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post.',
+    'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post. The output says whether every matching file is shown; page with offset (offset + limit up to 1000) when it is not.',
   inputSchema: z.object({
     limit: z
       .number()
@@ -13,6 +14,12 @@ export const listMediaTool = {
       .max(50)
       .optional()
       .describe('Number of assets to return (default 10, max 50)'),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('How many assets to skip. Use the offset the previous page gives to get the next page.'),
     drop_session_id: z
       .string()
       .optional()
@@ -21,14 +28,18 @@ export const listMediaTool = {
 
   async execute(
     client: PosterlyClient,
-    input: { limit?: number; drop_session_id?: string },
+    input: { limit?: number; offset?: number; drop_session_id?: string },
   ) {
     const result = await client.listMedia({
       limit: input.limit,
+      offset: input.offset,
       dropSessionId: input.drop_session_id,
     });
 
     if (result.media.length === 0) {
+      if ((input.offset ?? 0) > 0 && result.total > 0) {
+        return `No media on this page: offset ${input.offset} is past the last of the ${result.total} matching files.`;
+      }
       return 'No media found. If you just sent a drop URL, wait for the user to finish uploading, then call list_media again.';
     }
 
@@ -38,10 +49,20 @@ export const listMediaTool = {
       return `• ${item.filename} (${item.mime || 'unknown'}, ${size})${drop}\n  public_url: ${item.public_url}`;
     });
 
+    const offset = result.offset ?? input.offset ?? 0;
     return [
       `Media (${result.media.length} of ${result.total}):`,
       ...lines,
       '',
+      formatPagingNote({
+        noun: 'files',
+        tool: 'list_media',
+        offset,
+        count: result.media.length,
+        total: result.total,
+        hasMore: result.has_more ?? offset + result.media.length < result.total,
+        nextOffset: result.next_offset,
+      }),
       'Pass public_url to validate_post / create_post. Do not invent URLs.',
     ].join('\n');
   },

package/src/tools/list-post-suggestions.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
-import { mdTitle, mdSection, mdKeyValue, mdEmpty, truncateText } from '../lib/format.js';
+import { formatPagingNote, mdTitle, mdSection, mdKeyValue, mdEmpty, truncateText } from '../lib/format.js';
 
 export const listPostSuggestionsTool = {
   name: 'list_post_suggestions',
   description:
-    "List proactive post suggestions: evidence-based weekly drafts posterly writes in each account's learned voice, each with a rationale tying it back to what has performed well for that account. Filter by account_id and status (pending, scheduled, dismissed; default pending). Read-only; requires a Pro plan or higher. Use dismiss_suggestion to hide one.",
+    "List proactive post suggestions: evidence-based weekly drafts posterly writes in each account's learned voice, each with a rationale tying it back to what has performed well for that account. Filter by account_id and status (pending, scheduled, dismissed; default pending). The output says whether every matching suggestion is shown; page with offset until it does. Read-only; requires a Pro plan or higher. Use dismiss_suggestion to hide one.",
   inputSchema: z.object({
     account_id: z
       .union([z.string(), z.number()])
@@ -16,6 +16,7 @@ export const listPostSuggestionsTool = {
       .optional()
       .describe('Suggestion status to list (default pending).'),
     limit: z.number().int().min(1).max(100).optional().describe('Max suggestions to return (default 20).'),
+    offset: z.number().int().min(0).optional().describe('How many suggestions to skip. Use the offset the previous page gives to get the next page.'),
   }),
 
   async execute(
@@ -24,9 +25,11 @@ export const listPostSuggestionsTool = {
       account_id?: string | number;
       status?: 'pending' | 'scheduled' | 'dismissed';
       limit?: number;
+      offset?: number;
     },
   ) {
-    const { suggestions } = await client.listPostSuggestions(input);
+    const page = await client.listPostSuggestions(input);
+    const { suggestions } = page;
 
     if (!suggestions.length) {
       return mdEmpty(
@@ -51,6 +54,16 @@ export const listPostSuggestionsTool = {
       );
     });
 
-    return [mdTitle(`Post suggestions (${suggestions.length})`), ...blocks].join('\n\n');
+    const note = formatPagingNote({
+      noun: 'suggestions',
+      tool: 'list_post_suggestions',
+      offset: page.offset ?? input.offset ?? 0,
+      count: suggestions.length,
+      total: page.total,
+      // An API older than has_more: a full page may mean more exist.
+      hasMore: page.has_more ?? suggestions.length >= (input.limit || 20),
+      nextOffset: page.next_offset,
+    });
+    return [mdTitle(`Post suggestions (${suggestions.length})`), ...blocks, note].join('\n\n');
   },
 };

package/src/tools/list-posts.ts

@@ -1,13 +1,31 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { dashboardUrlForPostList, formatLocalDateTime, truncateText } from '../lib/format.js';
+import type { ListPostsParams, PosterlyClient } from '../lib/api-client.js';
+import { dashboardUrlForPostList, formatPostCounts, formatPostListPage } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
 
+type ListPostsInput = ListPostsParams & {
+  view?: 'list' | 'counts';
+  limit?: number;
+  offset?: number;
+  order?: 'asc' | 'desc';
+};
+
+export const LIST_POSTS_DESCRIPTION =
+  'Posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to. ' +
+  'view=list (default): posts filtered by status (scheduled, published, failed, draft), platform, account_id, workspace_id, brand_id, approval_status, approval_waiting_on, and a scheduled date range: scheduled_from (inclusive) and scheduled_to (a plain date includes that whole day), read in timezone (IANA, default UTC; also the zone times are shown in). Returns limit posts (default 20, max 200) starting at offset; with a date range the order defaults to oldest first (order=asc|desc). ' +
+  'The output always says whether every matching post was shown. If it says more are available, call again with the offset it gives and keep paging until all are shown before drawing any conclusion about totals, gaps, or how busy a client is. ' +
+  'view=counts (scheduled_from and scheduled_to required, up to 366 days): exact totals per day, status, account, and brand for the same filters (limit, offset, and order are ignored); use it for "how many" or "is this month full" questions. ' +
+  'approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval.';
+
 export const listPostsTool = {
   name: 'list_posts',
-  description:
-    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, approval_waiting_on, or brand_id. approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval. Returns posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to.',
+  description: LIST_POSTS_DESCRIPTION,
   inputSchema: z.object({
+    view: z
+      .enum(['list', 'counts'])
+      .optional()
+      .describe('list (default): the posts themselves, one page at a time. counts: exact totals per day, status, account, and brand (needs scheduled_from and scheduled_to).'),
     status: z
       .string()
       .optional()
@@ -20,12 +38,34 @@ export const listPostsTool = {
       .string()
       .optional()
       .describe('Filter to a specific social account ID (from list_accounts).'),
+    scheduled_from: z
+      .string()
+      .optional()
+      .describe('Start of the scheduled range, inclusive: a date (2026-10-01) or an ISO date-time. Plain dates and times without an offset are read in timezone.'),
+    scheduled_to: z
+      .string()
+      .optional()
+      .describe('End of the scheduled range: a plain date (2026-10-31) includes that whole day; an ISO date-time is exclusive.'),
+    timezone: z
+      .string()
+      .optional()
+      .describe('IANA time zone such as Europe/London for reading plain dates and showing times. Default UTC.'),
+    order: z
+      .enum(['asc', 'desc'])
+      .optional()
+      .describe('asc (oldest first) or desc (newest first). Default asc with a date range, otherwise desc. Ignored by view=counts.'),
     limit: z
       .number()
       .min(1)
-      .max(100)
+      .max(200)
+      .optional()
+      .describe('Posts per page (default 20, max 200). Ignored by view=counts.'),
+    offset: z
+      .number()
+      .int()
+      .min(0)
       .optional()
-      .describe('Number of posts to return (default 20, max 100)'),
+      .describe('How many matching posts to skip. Use the offset the previous page gives to get the next page. Ignored by view=counts.'),
     workspace_id: z
       .string()
       .optional()
@@ -44,48 +84,37 @@ export const listPostsTool = {
       .describe('Filter to posts assigned to a specific brand/client (the id from list_brands).'),
   }),
 
-  async execute(
-    client: PosterlyClient,
-    input: {
-      status?: string;
-      platform?: string;
-      account_id?: string;
-      limit?: number;
-      workspace_id?: string;
-      approval_status?: string;
-      approval_waiting_on?: 'client' | 'team';
-      brand_id?: string;
-    }
-  ) {
-    const { posts, total } = await client.listPosts({
-      ...input,
-      limit: input.limit || 20,
-    });
+  async execute(client: PosterlyClient, input: ListPostsInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'list_posts', input);
+    const filters = postFilters(args as ListPostsInput);
+    const timeZone = filters.timezone || 'UTC';
 
-    if (posts.length === 0) {
-      return 'No posts found matching your criteria.\n\nNext step for the AI agent: tell the user their posterly queue is clear for that filter, then ask what they want to schedule next.';
+    if (mode === 'counts') {
+      return formatPostCounts(await client.countPosts(filters));
     }
 
-    const lines = posts.map((p) => {
-      const date = formatLocalDateTime(p.scheduled_at);
-      const caption = truncateText(p.content, 60);
-      const approvalBits: string[] = [];
-      if (p.approval && p.approval.status !== 'none') {
-        approvalBits.push(`approval: ${p.approval.status}`);
-        if (p.approval.waiting_on) approvalBits.push(`waiting on: ${p.approval.waiting_on}`);
-      }
-      if (p.brand_id) approvalBits.push(`brand: ${p.brand_id}`);
-      if (p.content_plan_id) approvalBits.push(`plan: ${p.content_plan_id}`);
-      const approvalSuffix = approvalBits.length > 0 ? ` [${approvalBits.join(', ')}]` : '';
-      return `• [${p.status}] #${p.id}: ${caption} (${date})${approvalSuffix}`;
+    const hasRange = Boolean(filters.scheduled_from || filters.scheduled_to);
+    const page = await client.listPosts({
+      ...filters,
+      limit: (args as ListPostsInput).limit || 20,
+      offset: (args as ListPostsInput).offset,
+      order: (args as ListPostsInput).order ?? (hasRange ? 'asc' : undefined),
     });
-
-    return [
-      `Posts (${posts.length} of ${total}):`,
-      ...lines,
-      '',
-      `View in posterly: ${dashboardUrlForPostList(posts)}`,
-      'Next step for the AI agent: summarize the queue in plain language and use the dashboard link above if the user wants to inspect it in posterly.',
-    ].join('\n');
+    return formatPostListPage(page, { timeZone, dashboardUrl: dashboardUrlForPostList(page.posts || []) });
   },
 };
+
+function postFilters(input: ListPostsInput): ListPostsParams {
+  return {
+    status: input.status,
+    platform: input.platform,
+    account_id: input.account_id,
+    workspace_id: input.workspace_id,
+    approval_status: input.approval_status,
+    approval_waiting_on: input.approval_waiting_on,
+    brand_id: input.brand_id,
+    scheduled_from: input.scheduled_from,
+    scheduled_to: input.scheduled_to,
+    timezone: input.timezone,
+  };
+}