posterly-mcp-server 0.19.1 → 0.19.2

package/src/tools/create-post.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import { code, formatDateTime, mdKeyValue, mdSuccess, statusLabel } from '../lib/format.js';
 
 export const instagramSettingsSchema = z.object({
   __type: z.enum(['instagram', 'instagram-standalone']).optional(),
@@ -179,33 +180,24 @@ export const createPostTool = {
     const p = result.post as Record<string, any>;
     const ws = result.workspace;
 
-    const when = p.scheduled_at
-      ? new Date(p.scheduled_at).toLocaleString()
-      : 'now';
-
-    const lines = [
-      'Post created successfully!',
-      `• ID: ${p.id}`,
-      `• Platform: ${p.platform || input.platform || 'unknown'}`,
-      `• Type: ${p.post_type}`,
-      `• Status: ${p.status}`,
-      `• Scheduled: ${when}`,
-    ];
-    if (thread_posts) {
-      lines.push(`• Thread: ${thread_posts.length} posts`);
-    }
-    if (instagram_settings?.collaborators?.length) {
-      lines.push(`• Instagram collaborators: ${instagram_settings.collaborators.length}`);
-    }
-    if (instagram_settings?.first_comment) {
-      lines.push('• Instagram first comment: yes');
-    }
-    if (platform_settings) {
-      lines.push('• Platform settings: yes');
-    }
-    if (ws) {
-      lines.push(`• Workspace: ${ws.name} (${ws.id}) — resolved from ${ws.resolved_from}`);
-    }
-    return lines.join('\n');
+    return [
+      mdSuccess('Post created', [
+        ['Post ID', code(p.id)],
+        ['Platform', p.platform || input.platform || 'unknown'],
+        ['Type', p.post_type],
+        ['Status', statusLabel(p.status)],
+        ['Scheduled', p.scheduled_at ? formatDateTime(p.scheduled_at) : 'now'],
+        ['Thread', thread_posts ? `${thread_posts.length} posts` : undefined],
+        ['Instagram collaborators', instagram_settings?.collaborators?.length],
+        ['Instagram first comment', Boolean(instagram_settings?.first_comment)],
+        ['Platform settings', Boolean(platform_settings)],
+      ], 'Use `get_post` if you want to review the saved post details.'),
+      ws
+        ? mdKeyValue([
+          ['Workspace', `${ws.name} (${code(ws.id)})`],
+          ['Workspace resolved from', ws.resolved_from],
+        ])
+        : '',
+    ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/create-posts-batch.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { buildCreatePostPayload, createPostInputSchema, type CreatePostInput } from './create-post.js';
+import { code, formatDateTime, mdSection, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const createPostsBatchTool = {
   name: 'create_posts_batch',
@@ -23,26 +24,30 @@ export const createPostsBatchTool = {
     const payloads = input.posts.map((post) => buildCreatePostPayload(post));
     const result = await client.createPostsBatch({ posts: payloads });
 
-    const lines = [
-      'Batch create completed.',
-      `• Total: ${result.total}`,
-      `• Created: ${result.created}`,
-      `• Replayed: ${result.replayed}`,
-      `• Failed: ${result.failed}`,
-    ];
-
-    for (const item of result.posts.slice(0, 25)) {
+    const createdRows = result.posts.slice(0, 25).map((item) => {
       const post = item.post as Record<string, any>;
-      const when = post.scheduled_at ? new Date(post.scheduled_at).toLocaleString() : 'now';
-      lines.push(
-        `• [${item.index}] ID ${post.id} ${post.platform || 'unknown'} ${post.post_type || 'post'} ${post.status || 'created'} at ${when}${item.replayed ? ' (replayed)' : ''}`,
-      );
-    }
+      return [
+        item.index,
+        code(post.id),
+        post.platform || 'unknown',
+        post.post_type || 'post',
+        statusLabel(post.status || 'created'),
+        post.scheduled_at ? formatDateTime(post.scheduled_at) : 'now',
+        item.replayed ? 'yes' : 'no',
+      ];
+    });
 
-    for (const error of result.errors.slice(0, 25)) {
-      lines.push(`• [${error.index}] ERROR ${error.status}: ${error.error}`);
-    }
+    const errorRows = result.errors.slice(0, 25).map((error) => [
+      error.index,
+      error.status,
+      error.error,
+    ]);
 
-    return lines.join('\n');
+    return [
+      mdTitle(result.failed ? '⚠️ Batch create completed with issues' : '✅ Batch create completed'),
+      mdTable(['Total', 'Created', 'Replayed', 'Failed'], [[result.total, result.created, result.replayed, result.failed]]),
+      mdSection('Created posts', mdTable(['Index', 'Post ID', 'Platform', 'Type', 'Status', 'Scheduled', 'Replayed'], createdRows)),
+      mdSection('Errors', mdTable(['Index', 'Status', 'Error'], errorRows)),
+    ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/create-signed-upload.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, formatBytes, mdSuccess } from '../lib/format.js';
 
 export const createSignedUploadTool = {
   name: 'create_signed_upload',
   description:
-    'Create a signed direct-upload URL for a larger image or video. Upload the binary to upload_url, then use public_url with create_post.',
+    'Create a signed upload URL for a larger image or video. Upload the binary to upload_url; the API validates actual bytes before storage, then public_url can be used with create_post.',
   inputSchema: z.object({
     filename: z.string().describe('Filename with extension, e.g. launch-video.mp4'),
     content_type: z.string().describe('MIME type, e.g. video/mp4'),
@@ -16,12 +17,14 @@ export const createSignedUploadTool = {
     input: { filename: string; content_type: string; size: number },
   ) {
     const signed = await client.getSignedUploadUrl(input.filename, input.content_type, input.size);
-    return [
-      'Signed upload created.',
-      `• Upload URL: ${signed.upload_url}`,
-      `• Token: ${signed.token}`,
-      `• Storage path: ${signed.path}`,
-      `• Public URL after upload: ${signed.public_url}`,
-    ].join('\n');
+    return mdSuccess('Signed upload created', [
+      ['Filename', input.filename],
+      ['Content type', input.content_type],
+      ['Size', formatBytes(input.size)],
+      ['Upload URL', signed.upload_url],
+      ['Token', code(signed.token)],
+      ['Storage path', signed.path],
+      ['Public URL after upload', signed.public_url],
+    ]);
   },
 };

package/src/tools/create-webhook.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { webhookEventSchema } from './webhook-events.js';
+import { code, mdSuccess } from '../lib/format.js';
 
 export const createWebhookTool = {
   name: 'create_webhook',
@@ -28,8 +29,11 @@ export const createWebhookTool = {
   ) {
     const { confirm: _confirm, ...payload } = input;
     const result = await client.createWebhook(payload);
-    const secret = result.secret ? `\nSigning secret: ${result.secret}` : '';
-    return `Webhook created: ${result.webhook.id}\nURL: ${result.webhook.url}\nEvents: ${result.webhook.events.join(', ')}${secret}`;
+    return mdSuccess('Webhook created', [
+      ['Webhook ID', code(result.webhook.id)],
+      ['URL', result.webhook.url],
+      ['Events', result.webhook.events.join(', ')],
+      ['Signing secret', result.secret ? code(result.secret) : undefined],
+    ], 'Store the signing secret now; Posterly only returns it once.');
   },
 };
-

package/src/tools/delete-google-business-review-reply.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdSuccess } from '../lib/format.js';
 
 export const deleteGoogleBusinessReviewReplyTool = {
   name: 'delete_google_business_review_reply',
@@ -25,6 +26,8 @@ export const deleteGoogleBusinessReviewReplyTool = {
   ) {
     const { confirm: _confirm, ...payload } = input;
     const result = await client.deleteGoogleBusinessReviewReply(payload);
-    return result.message || 'Google Business review reply deleted successfully.';
+    return mdSuccess('Google Business review reply deleted', [
+      ['Message', result.message || 'Google Business review reply deleted successfully.'],
+    ]);
   },
 };

package/src/tools/delete-oauth-client.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess } from '../lib/format.js';
 
 export const deleteOAuthClientTool = {
   name: 'delete_oauth_client',
@@ -18,6 +19,8 @@ export const deleteOAuthClientTool = {
     },
   ) {
     const result = await client.deleteOAuthClient(input.client_id);
-    return `OAuth client deleted: ${result.client_id}`;
+    return mdSuccess('OAuth client deleted', [
+      ['Client ID', code(result.client_id)],
+    ]);
   },
 };

package/src/tools/delete-post-group.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdJson, mdTitle } from '../lib/format.js';
 
 export const deletePostGroupTool = {
   name: 'delete_post_group',
@@ -12,6 +13,9 @@ export const deletePostGroupTool = {
 
   async execute(client: PosterlyClient, input: { group_id: string; confirm: true }) {
     const result = await client.deletePostGroup(input.group_id);
-    return JSON.stringify(result, null, 2);
+    return [
+      mdTitle('✅ Post group delete completed', `Group: ${input.group_id}`),
+      mdJson('Result', result),
+    ].join('\n\n');
   },
 };

package/src/tools/delete-post.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess } from '../lib/format.js';
 
 export const deletePostTool = {
   name: 'delete_post',
@@ -15,6 +16,8 @@ export const deletePostTool = {
     input: { post_id: number },
   ) {
     const result = await client.deletePost(input.post_id);
-    return `Post #${result.id} deleted successfully.`;
+    return mdSuccess('Post deleted', [
+      ['Post ID', code(result.id)],
+    ]);
   },
 };

package/src/tools/delete-webhook.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess } from '../lib/format.js';
 
 export const deleteWebhookTool = {
   name: 'delete_webhook',
@@ -12,7 +13,8 @@ export const deleteWebhookTool = {
 
   async execute(client: PosterlyClient, input: { webhook_id: string; confirm: true }) {
     const result = await client.deleteWebhook(input.webhook_id);
-    return `Webhook deleted: ${result.id}`;
+    return mdSuccess('Webhook deleted', [
+      ['Webhook ID', code(result.id)],
+    ]);
   },
 };
-

package/src/tools/disconnect-account.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess } from '../lib/format.js';
 
 export const disconnectAccountTool = {
   name: 'disconnect_account',
@@ -21,10 +22,11 @@ export const disconnectAccountTool = {
 
     const result = await client.disconnectAccount(input.account_id);
     const account = result.account || {};
-    return [
-      `Disconnected ${account.platform || 'account'}${account.username ? ` @${account.username}` : ''} (ID: ${account.id || input.account_id}).`,
-      `Transferred posts: ${result.transferred_post_count ?? 0}.`,
-      `Stamped posts: ${result.stamped_post_count ?? 0}.`,
-    ].join('\n');
+    return mdSuccess('Account disconnected', [
+      ['Account', `${account.platform || 'account'}${account.username ? ` @${account.username}` : ''}`],
+      ['Account ID', code(account.id || input.account_id)],
+      ['Transferred posts', result.transferred_post_count ?? 0],
+      ['Stamped posts', result.stamped_post_count ?? 0],
+    ]);
   },
 };

package/src/tools/find-slot.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { formatDate, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
 
 export const findSlotTool = {
   name: 'find_available_slot',
@@ -38,12 +39,19 @@ export const findSlotTool = {
     const slots = await client.findAvailableSlots(input);
 
     if (slots.length === 0) {
-      return 'No available slots found in the next 14 days.';
+      return mdEmpty('available slots', 'No available posting slots were found in the next 14 days.');
     }
 
-    const lines = slots.map(
-      (s, i) => `${i + 1}. ${s.local_time} — ${new Date(s.time).toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' })}`
-    );
-    return `Available posting slots:\n${lines.join('\n')}`;
+    return [
+      mdTitle(`Available posting slots (${slots.length})`),
+      mdTable(
+        ['Option', 'Local time', 'Date'],
+        slots.map((slot, index) => [
+          index + 1,
+          slot.local_time,
+          formatDate(slot.time),
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

package/src/tools/generate-image.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdBullets, mdKeyValue, mdSection, mdTable, mdTitle } from '../lib/format.js';
 
 export const generateImageTool = {
   name: 'generate_image',
@@ -62,25 +63,24 @@ export const generateImageTool = {
   ) {
     const result = await client.generateImage(input);
 
-    const lines: string[] = [];
-    lines.push(`Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'} via ${result.model}.`);
-    lines.push('');
-    result.images.forEach((img, i) => {
-      lines.push(`${i + 1}. ${img.url}`);
-    });
-    lines.push('');
-    lines.push(`Billed from: ${result.usage.billed_from}${result.credits_used > 0 ? ` (${result.credits_used} credits)` : ''}`);
-    if (result.usage.limit != null) {
-      lines.push(`Plan usage: ${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}${result.usage.tier ? ` (${result.usage.tier})` : ''}`);
-    }
-    if (result.warnings?.length) {
-      lines.push('');
-      lines.push('Warnings:');
-      result.warnings.forEach((w) => lines.push(`• ${w}`));
-    }
-    lines.push('');
-    lines.push('Pass any of these URLs to create_post as media_url (or media_urls for a carousel).');
-
-    return lines.join('\n');
+    return [
+      mdTitle(`✅ Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'}`, `Model: ${result.model}`),
+      mdTable(
+        ['#', 'Image URL', 'Filename'],
+        result.images.map((img, index) => [
+          index + 1,
+          img.url,
+          img.filename,
+        ]),
+      ),
+      mdKeyValue([
+        ['Billed from', result.usage.billed_from],
+        ['Credits used', result.credits_used],
+        ['Plan usage', result.usage.limit != null ? `${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}` : undefined],
+        ['Plan tier', result.usage.tier || undefined],
+      ]),
+      result.warnings?.length ? mdSection('Warnings', mdBullets(result.warnings)) : '',
+      '**Next step:** Pass any URL above to `create_post` as `media_url`, or use multiple as `media_urls` for a carousel.',
+    ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/generate-video.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdJson, mdKeyValue, mdTitle, statusLabel } from '../lib/format.js';
 
 export const generateVideoTool = {
   name: 'generate_video',
@@ -25,14 +26,15 @@ export const generateVideoTool = {
   async execute(client: PosterlyClient, input: any) {
     const result = await client.generateVideo(input);
     return [
-      'Video generation job queued',
-      `Job ID: ${result.job_id}`,
-      `Status: ${result.status}`,
-      `Credit cost: ${result.credit_cost} (${result.included_credit_cost || 0} included, ${result.purchased_credit_cost || 0} purchased)`,
-      result.message,
-      '',
-      'Raw response:',
-      JSON.stringify(result, null, 2),
-    ].filter(Boolean).join('\n');
+      mdTitle('🎬 Video generation job queued'),
+      mdKeyValue([
+        ['Job ID', code(result.job_id)],
+        ['Status', statusLabel(result.status)],
+        ['Credit cost', `${result.credit_cost} (${result.included_credit_cost || 0} included, ${result.purchased_credit_cost || 0} purchased)`],
+        ['Message', result.message],
+      ]),
+      '**Next step:** Poll `get_video_job` with the job ID until the video URL is ready.',
+      mdJson('Raw response', result),
+    ].filter(Boolean).join('\n\n');
   },
 };

package/src/tools/get-account-analytics.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { AccountAnalyticsSummary, PosterlyClient } from '../lib/api-client.js';
+import { formatDelta, formatNumber, formatPercent, mdBullets, mdKeyValue, mdSection, mdTable, mdTitle } from '../lib/format.js';
 
 export const getAccountAnalyticsTool = {
   name: 'get_account_analytics',
@@ -26,62 +27,82 @@ export const getAccountAnalyticsTool = {
     const result = await client.getAccountAnalytics(input);
     const { account, range, summary, snapshots } = result;
 
-    const lines: string[] = [
-      `Analytics for @${account.username} (${account.platform}, id ${account.id})`,
-      `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
-      '',
-      'Summary:',
-    ];
+    const metricRows = account.platform === 'google_business'
+      ? googleBusinessMetricRows(summary)
+      : genericMetricRows(summary, account.platform);
 
-    if (account.platform === 'google_business') {
-      const metrics = summary.platform_metrics || {};
-      pushMetric(lines, 'Profile views', metrics.profile_views ?? summary.total_views);
-      pushMetric(lines, 'Search views', metrics.search_views ?? summary.total_reach);
-      pushMetric(lines, 'Maps views', metrics.maps_views ?? summary.total_profile_views);
-      pushMetric(lines, 'Customer actions', metrics.customer_actions ?? summary.total_accounts_engaged);
-      pushMetric(lines, 'Posts', metrics.posts ?? summary.current_media_count);
-      lines.push(`• Engagement rate (actions / profile views): ${summary.engagement_rate}%`);
-      pushMetric(lines, 'Website clicks', metrics.website_clicks ?? summary.total_website_clicks);
-      pushMetric(lines, 'Call clicks', metrics.call_clicks ?? summary.total_call_clicks);
-      pushMetric(lines, 'Direction requests', metrics.direction_requests ?? summary.total_direction_requests);
-      pushMetric(lines, 'Conversations', metrics.conversations ?? summary.total_conversations);
-      pushMetric(lines, 'Bookings', metrics.bookings ?? summary.total_bookings);
-    } else if (account.platform === 'pinterest') {
-      pushGenericSummary(lines, summary);
-      pushMetric(lines, 'Outbound clicks', summary.total_website_clicks);
-    } else if (account.platform === 'youtube') {
-      pushGenericSummary(lines, summary);
-      pushMetric(lines, 'Watch minutes', summary.total_watch_minutes);
-      pushMetric(lines, 'Likes', summary.total_likes);
-    } else {
-      pushGenericSummary(lines, summary);
-    }
-
-    return lines.join('\n');
+    return [
+      mdTitle(`📊 Analytics for @${account.username}`, `${account.platform} · ${range.from} → ${range.to}`),
+      mdKeyValue([
+        ['Account ID', account.id],
+        ['Daily snapshots', snapshots.length],
+      ]),
+      mdSection('Summary', mdTable(['Metric', 'Value'], metricRows)),
+      mdSection('Quick read', mdBullets(buildInsights(summary, account.platform))),
+    ].filter(Boolean).join('\n\n');
   },
 };
 
-function formatDelta(n: number): string {
-  return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
+function genericMetricRows(summary: AccountAnalyticsSummary, platform: string) {
+  const rows: Array<[string, string]> = [
+    ['Followers', `${formatNumber(summary.current_followers)} (${formatDelta(summary.followers_change)} in range)`],
+    ['Follows gained / lost', `+${formatNumber(summary.total_follows_gained)} / -${formatNumber(summary.total_follows_lost)}`],
+    ['Total reach', formatNumber(summary.total_reach)],
+    ['Total views', formatNumber(summary.total_views)],
+    ['Profile views', formatNumber(summary.total_profile_views)],
+    ['Accounts engaged', formatNumber(summary.total_accounts_engaged)],
+    ['Engagement rate by reach', formatPercent(summary.engagement_rate)],
+    ['Engagement rate by followers', formatPercent(summary.engagement_rate_by_followers)],
+  ];
+
+  if (platform === 'pinterest') {
+    rows.push(['Outbound clicks', formatNumber(summary.total_website_clicks)]);
+  }
+  if (platform === 'youtube') {
+    rows.push(['Watch minutes', formatNumber(summary.total_watch_minutes)]);
+    rows.push(['Likes', formatNumber(summary.total_likes)]);
+  }
+
+  return rows;
 }
 
-function pushGenericSummary(lines: string[], summary: AccountAnalyticsSummary) {
-  lines.push(
-    `• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`,
-    `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`
-  );
-  pushMetric(lines, 'Total reach', summary.total_reach);
-  pushMetric(lines, 'Total views', summary.total_views);
-  pushMetric(lines, 'Profile views', summary.total_profile_views);
-  pushMetric(lines, 'Total accounts engaged', summary.total_accounts_engaged);
-  lines.push(
-    `• Engagement rate (by reach): ${summary.engagement_rate}%`,
-    `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`
-  );
+function googleBusinessMetricRows(summary: AccountAnalyticsSummary) {
+  const metrics = summary.platform_metrics || {};
+  return [
+    ['Profile views', formatNumber(metrics.profile_views ?? summary.total_views)],
+    ['Search views', formatNumber(metrics.search_views ?? summary.total_reach)],
+    ['Maps views', formatNumber(metrics.maps_views ?? summary.total_profile_views)],
+    ['Customer actions', formatNumber(metrics.customer_actions ?? summary.total_accounts_engaged)],
+    ['Posts', formatNumber(metrics.posts ?? summary.current_media_count)],
+    ['Engagement rate (actions / profile views)', formatPercent(summary.engagement_rate)],
+    ['Website clicks', formatNumber(metrics.website_clicks ?? summary.total_website_clicks)],
+    ['Call clicks', formatNumber(metrics.call_clicks ?? summary.total_call_clicks)],
+    ['Direction requests', formatNumber(metrics.direction_requests ?? summary.total_direction_requests)],
+    ['Conversations', formatNumber(metrics.conversations ?? summary.total_conversations)],
+    ['Bookings', formatNumber(metrics.bookings ?? summary.total_bookings)],
+  ];
 }
 
-function pushMetric(lines: string[], label: string, value: number | null | undefined) {
-  if (value != null) {
-    lines.push(`• ${label}: ${value.toLocaleString()}`);
+function buildInsights(summary: AccountAnalyticsSummary, platform: string): string[] {
+  const insights: string[] = [];
+
+  if (summary.followers_change > 0) {
+    insights.push(`Audience grew by ${formatDelta(summary.followers_change)} followers in this range.`);
+  } else if (summary.followers_change < 0) {
+    insights.push(`Audience dipped by ${formatDelta(summary.followers_change)} followers in this range.`);
   }
+
+  if (summary.engagement_rate != null) {
+    insights.push(`Engagement by reach is ${formatPercent(summary.engagement_rate)}.`);
+  }
+
+  if (platform === 'google_business' && summary.total_website_clicks != null) {
+    insights.push(`${formatNumber(summary.total_website_clicks)} website clicks came from the profile.`);
+  }
+
+  if (platform === 'youtube' && summary.total_watch_minutes != null) {
+    insights.push(`${formatNumber(summary.total_watch_minutes)} total watch minutes were recorded.`);
+  }
+
+  return insights.length > 0 ? insights : ['No standout movement detected in the returned period.'];
 }

package/src/tools/get-brand-profile.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, compactText, formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
 
 export const getBrandProfileTool = {
   name: 'get_brand_profile',
@@ -16,48 +17,43 @@ export const getBrandProfileTool = {
     const result = await client.getBrandProfile(input.brand_id);
     const profile = result.brand_profile as Record<string, any>;
 
-    const lines = [
-      `Brand profile: ${profile.brand_name}`,
-      `• Source: ${profile.source}`,
-    ];
+    const profileBody = [
+      mdKeyValue([
+        ['Source', profile.source],
+        ['Profile ID', profile.id ? code(profile.id) : undefined],
+        ['Workspace client ID', profile.workspace_client_id ? code(profile.workspace_client_id) : undefined],
+        ['Legacy brand group ID', profile.brand_group_id ? code(profile.brand_group_id) : undefined],
+        ['Logo', profile.logo_url],
+        ['Last refreshed', profile.last_context_refresh_at ? formatDateTime(profile.last_context_refresh_at) : undefined],
+      ]),
+      mdSection('Voice and audience', mdKeyValue([
+        ['Tone of voice', compactText(profile.tone_of_voice, 180)],
+        ['Audience', compactText(profile.audience, 180)],
+        ['Brand values', compactText(profile.brand_values, 180)],
+        ['Brand story', compactText(formatStructuredValue(profile.brand_story), 240)],
+      ])),
+      mdSection('Guidance', mdKeyValue([
+        ['Custom instructions', compactText(profile.custom_instructions, 240)],
+        ['Keywords', formatStructuredValue(profile.keywords)],
+        ['Competitors', formatStructuredValue(profile.competitors)],
+        ['Do / Don’ts', formatStructuredValue(profile.do_donts)],
+        ['Topics to cover', formatStructuredValue(profile.topics_to_cover)],
+        ['Topics to avoid', formatStructuredValue(profile.topics_to_avoid)],
+      ])),
+      mdSection('Creative references', mdKeyValue([
+        ['Visual guidelines', formatStructuredValue(profile.visual_guidelines)],
+        ['Example posts', formatStructuredValue(profile.example_posts)],
+        ['Voice examples', formatStructuredValue(profile.voice_examples)],
+      ])),
+    ].filter(Boolean).join('\n\n');
 
-    if (profile.workspace_client_id) lines.push(`• Workspace client ID: ${profile.workspace_client_id}`);
-    if (profile.brand_group_id) lines.push(`• Legacy brand group ID: ${profile.brand_group_id}`);
-    if (profile.tone_of_voice) lines.push(`• Tone of voice: ${profile.tone_of_voice}`);
-    if (profile.audience) lines.push(`• Audience: ${profile.audience}`);
-    if (profile.brand_values) lines.push(`• Brand values: ${profile.brand_values}`);
-    if (profile.custom_instructions) lines.push(`• Custom instructions: ${profile.custom_instructions}`);
-    if (profile.logo_url) lines.push(`• Logo URL: ${profile.logo_url}`);
-
-    addStructuredLine(lines, 'Keywords', profile.keywords);
-    addStructuredLine(lines, 'Competitors', profile.competitors);
-    addStructuredLine(lines, 'Do / Don’ts', profile.do_donts);
-    addStructuredLine(lines, 'Visual guidelines', profile.visual_guidelines);
-    addStructuredLine(lines, 'Brand story', profile.brand_story);
-    addStructuredLine(lines, 'Example posts', profile.example_posts);
-    addStructuredLine(lines, 'Topics to cover', profile.topics_to_cover);
-    addStructuredLine(lines, 'Topics to avoid', profile.topics_to_avoid);
-    addStructuredLine(lines, 'Voice examples', profile.voice_examples);
-
-    if (profile.last_context_refresh_at) {
-      lines.push(`• Last refreshed: ${profile.last_context_refresh_at}`);
-    }
-
-    if (lines.length === 2) {
-      lines.push('• No extended brand profile fields have been saved yet.');
-    }
-
-    return lines.join('\n');
+    return [
+      mdTitle(`Brand profile: ${profile.brand_name}`),
+      profileBody || 'No extended brand profile fields have been saved yet.',
+    ].join('\n\n');
   },
 };
 
-function addStructuredLine(lines: string[], label: string, value: unknown) {
-  const formatted = formatStructuredValue(value);
-  if (formatted) {
-    lines.push(`• ${label}: ${formatted}`);
-  }
-}
-
 function formatStructuredValue(value: unknown): string | null {
   if (value == null) return null;
   if (typeof value === 'string') {