@sendinel/mcp-server 1.0.31 → 1.0.32

package/README.md

@@ -12,7 +12,7 @@ AI-controlled email operations control plane for campaigns, contacts, segments,
 
 ## Tool groups
 
-Sendinel currently exposes 34 tool groups and 315 tools (gateway mode adds 3 meta-tools). These counts are checked against the tool registry in CI, so this table matches what ships.
+Sendinel currently exposes 34 tool groups and 316 tools (gateway mode adds 3 meta-tools). These counts are checked against the tool registry in CI, so this table matches what ships.
 
 | Group | Count | Purpose |
 |-------|-------|---------|
@@ -23,7 +23,7 @@ Sendinel currently exposes 34 tool groups and 315 tools (gateway mode adds 3 met
 | `approvals` | 2 | Poll and list risk-tiered action approvals |
 | `automations` | 7 | Automation triggers, previews, and response-gated escalation ladders |
 | `brand_kit` | 5 | Brand Core text import, media library upload/URL ingest, asset-context reads |
-| `campaigns` | 39 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates |
+| `campaigns` | 40 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates |
 | `cloud-import` | 6 | Cloud storage import |
 | `compound` | 4 | Higher-level campaign/template/site setup and delivery diagnosis workflows |
 | `connector` | 6 | BYOD connector status, table discovery, schema/view setup, mapping, resync |

package/build/index.js

@@ -7,14 +7,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { registerAllTools } from './server.js';
+import { registerAllTools, SENDINEL_SERVER_INSTRUCTIONS } from './server.js';
 import { registerAllPrompts } from './prompts.js';
 import { runWithClient } from './db.js';
 import { initProjectClient, resolveProjectClientStrict, TenantResolutionError } from './byod-client.js';
 import { authenticateBearer, McpAuthenticationError, validateKey } from './auth.js';
 const transport = process.env.MCP_TRANSPORT ?? 'stdio';
 async function runStdio() {
-    const server = new McpServer({ name: 'sendinel', version: '0.1.0' });
+    const server = new McpServer({ name: 'sendinel', version: '0.1.0' }, { instructions: SENDINEL_SERVER_INSTRUCTIONS });
     // For stdio, validate SENDINEL_API_KEY and fail closed if it is absent.
     const apiKey = process.env.SENDINEL_API_KEY;
     let toolGroups;
@@ -94,7 +94,7 @@ async function runHttp() {
             throw err;
         }
         await runWithClient(projectClient, async () => {
-            const server = new McpServer({ name: 'sendinel', version: '0.1.0' });
+            const server = new McpServer({ name: 'sendinel', version: '0.1.0' }, { instructions: SENDINEL_SERVER_INSTRUCTIONS });
             registerAllTools(server, {
                 scopes: info.scopes,
                 toolGroups: info.toolGroups,

package/build/lib/action-approvals.d.ts

@@ -25,8 +25,15 @@ export interface ExecutionDecision {
 export declare function assertChannelCanExecute(action: string, params: Record<string, unknown> | undefined, context: ChannelExecutionContext): ExecutionDecision;
 /** Convenience: pull channel/verified out of the request-scoped context, defaulting to today's only live caller (mcp_api_key). */
 export declare function currentChannelContext(): ChannelExecutionContext;
+/**
+ * Display-only facts for the approval summary (segment name, count, subject, excerpt). Never
+ * stored in params, so it can't change the params an approval is checked against.
+ */
+export type ApprovalDisplay = Record<string, string | number | null | undefined>;
+/** Tag-stripped, whitespace-collapsed, length-capped text. HTML is untrusted input. */
+export declare function approvalExcerpt(html: unknown, max?: number): string;
 /** Build a human-readable summary of the action for the approval screen */
-export declare function buildApprovalSummary(action: string, params: Record<string, unknown>): string;
+export declare function buildApprovalSummary(action: string, params: Record<string, unknown>, display?: ApprovalDisplay): string;
 export interface ApprovalResult {
     requires_approval: true;
     approval_id: string;
@@ -43,7 +50,7 @@ export interface ApprovalResult {
  * Request human approval for an action. Creates a pending approval token
  * and returns instructions for the agent to wait.
  */
-export declare function requestApproval(action: string, params: Record<string, unknown>, apiKeyId?: string, channelContext?: ChannelExecutionContext): Promise<ApprovalResult>;
+export declare function requestApproval(action: string, params: Record<string, unknown>, apiKeyId?: string, channelContext?: ChannelExecutionContext, display?: ApprovalDisplay): Promise<ApprovalResult>;
 /**
  * Check if an approval token has been approved.
  * Returns the approval if approved, null if still pending, throws if rejected/expired.

package/build/lib/action-approvals.js

@@ -16,6 +16,7 @@ const GATED_ACTIONS = new Set([
     'resync_connector', // forces a full resync
     'publish_dmarc_record', // writes a DNS record into a customer-owned Cloudflare zone
     'broadcast_to_segment', // creates + activates a real broadcast
+    'send_broadcast', // one-call broadcast; executes a frozen, approved payload (#3669)
     'rotate_custom_webhook_secret', // immediately invalidates an inbound signing secret
     'create_campaign_with_content', // can activate + send in one call
     'enroll_segment', // bulk enrollment
@@ -49,6 +50,10 @@ export function getApprovalTier(action, params) {
             return 'autonomous';
         return 'protected';
     }
+    // send_broadcast exists for agents and always needs a person's approval, even in autonomous
+    // mode: it must never approve itself (#3669, AI-worker boundary in CLAUDE.md).
+    if (action === 'send_broadcast')
+        return 'gated';
     // Autonomous mode: user explicitly opted out of approval gates for gated actions
     // (request-scoped under HTTP — env is only trustworthy for single-project stdio)
     const mode = requestContext()?.approvalMode ?? process.env.SENDINEL_APPROVAL_MODE ?? 'standard';
@@ -123,8 +128,28 @@ export function currentChannelContext() {
         verified: ctx?.channelVerified ?? true,
     };
 }
+/** Tag-stripped, whitespace-collapsed, length-capped text. HTML is untrusted input. */
+export function approvalExcerpt(html, max = 200) {
+    const text = String(html ?? '')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function broadcastSummary(d) {
+    if (!d.subject)
+        return null;
+    const count = typeof d.recipient_count === 'number' ? `${d.recipient_count.toLocaleString('en-US')} recipient${d.recipient_count === 1 ? '' : 's'}` : null;
+    const audience = d.segment_name ? `segment "${d.segment_name}"` : (d.audience_label ? String(d.audience_label) : 'the chosen audience');
+    const when = d.send_at ? ` at ${d.send_at}` : '';
+    const excerpt = d.body_excerpt ? ` — "${d.body_excerpt}"` : '';
+    return `Send "${d.subject}" to ${audience}${count ? ` (${count})` : ''}${when}${excerpt}`;
+}
 /** Build a human-readable summary of the action for the approval screen */
-export function buildApprovalSummary(action, params) {
+export function buildApprovalSummary(action, params, display = {}) {
     const summaries = {
         launch_campaign: (p) => `Launch campaign "${p.name || p.campaign_name || 'unknown'}" — will send emails to real contacts`,
         install_connector_schema: (p) => `Install connector schema for project ${p.project_id ?? 'current'}`,
@@ -132,7 +157,20 @@ export function buildApprovalSummary(action, params) {
         set_connector_mapping: () => `Rewrite the BYOD connector field mapping`,
         resync_connector: () => `Force a full BYOD connector resync`,
         publish_dmarc_record: (p) => `Publish DMARC record for ${p.domain} - writes DNS in a customer-owned Cloudflare zone`,
-        broadcast_to_segment: (p) => `Broadcast "${p.name || p.subject || 'untitled'}" to segment ${p.segment_id} — will send emails to real contacts`,
+        broadcast_to_segment: (p) => broadcastSummary(display) ?? `Broadcast "${p.name || p.subject || 'untitled'}" to segment ${p.segment_id} — will send emails to real contacts`,
+        send_broadcast: (p) => {
+            const payload = (p.payload ?? {});
+            return broadcastSummary({
+                subject: payload.subject,
+                recipient_count: Array.isArray(payload.contact_ids) ? payload.contact_ids.length : undefined,
+                body_excerpt: approvalExcerpt(payload.body_html),
+                send_at: payload.send_at ?? undefined,
+                ...display,
+            }) ?? `Send a broadcast — will send emails to real contacts`;
+        },
+        update_campaign_status: (p) => (p.status === 'active'
+            ? `Activate campaign "${display.campaign_name ?? p.campaign_id}"${typeof display.enrolled === 'number' ? ` — sends email to ${display.enrolled.toLocaleString('en-US')} enrolled contact${display.enrolled === 1 ? '' : 's'}` : ' — will send emails to real contacts'}${display.trigger ? ` and to new contacts on "${display.trigger}"` : ''}`
+            : `Change campaign "${display.campaign_name ?? p.campaign_id}" to ${p.status}`),
         rotate_custom_webhook_secret: (p) => `Rotate custom webhook ${p.connection_id} signing secret — immediately invalidates the previous secret with no grace period`,
         create_campaign_with_content: (p) => `Create + activate campaign "${p.name}" with ${p.steps?.length ?? 0} email(s) and enroll contacts`,
         enroll_segment: (p) => `Enroll all contacts from site into campaign ${p.campaign_id}`,
@@ -178,9 +216,9 @@ function approvalParamsEqual(expected, actual) {
  * Request human approval for an action. Creates a pending approval token
  * and returns instructions for the agent to wait.
  */
-export async function requestApproval(action, params, apiKeyId, channelContext) {
+export async function requestApproval(action, params, apiKeyId, channelContext, display) {
     const tier = getApprovalTier(action, params);
-    const summary = buildApprovalSummary(action, params);
+    const summary = buildApprovalSummary(action, params, display);
     const expiresAt = new Date(Date.now() + 30 * 60 * 1000).toISOString();
     const { channel, verified } = channelContext ?? currentChannelContext();
     const { data, error } = await db()

package/build/lib/email-generation.d.ts

@@ -0,0 +1,11 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import { type ComposerBlock } from './composer-blocks.js';
+export declare function parseAudienceRules(anthropic: Anthropic, description: string): Promise<Record<string, unknown>>;
+export type GeneratedEmail = {
+    subject: string;
+    preview_text: string | null;
+    body_html: string;
+    body_text: string;
+    blocks: ComposerBlock[];
+};
+export declare function generateEmailFromBrief(anthropic: Anthropic, projectId: string, siteId: string, brief: string): Promise<GeneratedEmail>;

package/build/lib/email-generation.js

@@ -0,0 +1,92 @@
+import { db } from '../db.js';
+import { getAnthropicModelId } from '../anthropic-model.js';
+import { buildEmailSystemPrompt, buildVoicePrompt } from './voice.js';
+import { BLOCK_GENERATION_SCHEMA, blocksToHtml, blocksToText, normalizeComposerBlocks } from './composer-blocks.js';
+/**
+ * Shared AI helpers for the MCP send tools (#3669): turn a plain-language audience into segment
+ * rules, and turn a brief into a finished email (Brand Brain voice, Composer blocks rendered to
+ * HTML). Same prompts as launch_campaign. A failure throws: no placeholder email is ever produced.
+ */
+function parseJsonResponse(raw) {
+    return JSON.parse(raw.replace(/```json?\n?|```/g, '').trim());
+}
+function responseText(resp) {
+    const block = resp.content.find((b) => b.type === 'text');
+    return block && 'text' in block ? block.text : '';
+}
+export async function parseAudienceRules(anthropic, description) {
+    const resp = await anthropic.messages.create({
+        model: getAnthropicModelId(),
+        max_tokens: 512,
+        system: 'You translate natural language audience descriptions into a JSON filter rules object. Return ONLY valid JSON. Available keys: lifecycle_stage (lead|trial|customer|churned|win-back), payment (object with plan, mrr_cents, ltv_cents, subscription_status, trial_ends_at, churned_at, paid_at), min_score, max_score, source, subscribed_after, subscribed_before, has_opened, has_clicked, tag, custom_property, exclude_suppressed. Example: {"payment":{"plan":"pro","trial_ends_at":{"within_days":7}},"lifecycle_stage":"trial"}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
+        messages: [{ role: 'user', content: description }],
+    });
+    try {
+        const rules = parseJsonResponse(responseText(resp) || '{}');
+        if (!rules || typeof rules !== 'object' || Array.isArray(rules))
+            throw new Error('not an object');
+        return rules;
+    }
+    catch {
+        throw new Error(`Could not understand the audience "${description}". Try a saved segment instead.`);
+    }
+}
+export async function generateEmailFromBrief(anthropic, projectId, siteId, brief) {
+    const [{ data: site, error: siteError }, { data: project, error: projectError }] = await Promise.all([
+        db().from('sites').select('name, sending_domain, from_name, from_email, brand_voice').eq('id', siteId).eq('project_id', projectId).maybeSingle(),
+        db().from('projects').select('brand_settings').eq('id', projectId).maybeSingle(),
+    ]);
+    if (siteError)
+        throw siteError;
+    if (projectError)
+        throw projectError;
+    const brandCtx = site ? `Brand: ${site.name}, Domain: ${site.sending_domain}, From: ${site.from_name}` : '';
+    const voicePrompt = buildVoicePrompt(site?.brand_voice, project?.brand_settings ?? null);
+    const systemPrompt = `${buildEmailSystemPrompt(brandCtx, voicePrompt, project?.brand_settings ?? null)}
+
+Generate structured Composer blocks first. Return ONLY valid JSON with:
+{
+  "execution_trace": object,
+  "conclusion": {
+    "subject": string,
+    "preview_text": string,
+    "blocks": ComposerBlock[],
+    "body_text": string,
+    "cta_text": string,
+    "reasoning_log": string,
+    "brand_voice_compliance": "PASS" | string
+  }
+}
+
+ComposerBlock[] must conform to this JSON Schema:
+${JSON.stringify(BLOCK_GENERATION_SCHEMA)}
+
+Do not include body_html in your response; Sendinel renders body_html from blocks.`;
+    const resp = await anthropic.messages.create({
+        model: getAnthropicModelId(),
+        max_tokens: 3000,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: brief }],
+    });
+    let conclusion;
+    try {
+        const parsed = parseJsonResponse(responseText(resp) || '{}');
+        conclusion = parsed.conclusion ?? parsed;
+    }
+    catch {
+        throw new Error('The email draft came back in an unreadable format. Try again or pass html instead of brief.');
+    }
+    const blocks = normalizeComposerBlocks(conclusion?.blocks);
+    const subject = typeof conclusion?.subject === 'string' ? conclusion.subject.trim() : '';
+    if (!blocks.length || !subject) {
+        throw new Error('The email draft was empty. Try again or pass html instead of brief.');
+    }
+    const previewText = typeof conclusion.preview_text === 'string' ? conclusion.preview_text : null;
+    return {
+        subject,
+        preview_text: previewText,
+        body_html: blocksToHtml(blocks, { preheader: previewText }),
+        body_text: typeof conclusion.body_text === 'string' && conclusion.body_text.trim() ? conclusion.body_text : blocksToText(blocks),
+        blocks,
+    };
+}

package/build/lib/send-audience.d.ts

@@ -0,0 +1,24 @@
+import { type SegmentRules } from '@sendinel/domain';
+/**
+ * Who a broadcast can actually reach (#3669). One place for the MCP send tools so the count an
+ * approver sees is the count that gets enrolled:
+ *   - the shared segment base query (test, deleted, globally unsubscribed, cooled excluded),
+ *     paged and chunked (#3674), with suppressions removed;
+ *   - only people signed up to the sending site (the send step claims nobody else, #3668);
+ *   - the project's consent gate when it is on (#3667).
+ * Every read throws on failure: an unknown audience must never read as "nobody" or "everyone".
+ */
+export type SendClass = 'broadcast' | 'product';
+/** Contact ids matching segment rules (same semantics as the segments tools and the dashboard). */
+export declare function resolveSegmentContactIds(projectId: string, rules: SegmentRules): Promise<string[]>;
+export type SendAudience = {
+    /** People the send will enroll. */
+    contactIds: string[];
+    /** People matching the segment before the sender and consent checks. */
+    matched: number;
+    /** Matched but not signed up to the sending site. */
+    notOnSender: number;
+    /** Held back by the consent gate, by reason. Empty when the gate is off. */
+    heldBack: Record<string, number>;
+};
+export declare function resolveSendAudience(projectId: string, siteId: string, rules: SegmentRules, sendClass?: SendClass): Promise<SendAudience>;

package/build/lib/send-audience.js

@@ -0,0 +1,79 @@
+import { applySegmentRules, buildSegmentBaseQuery, chunkIds, evaluateSegmentRules, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
+import { db } from '../db.js';
+async function loadFieldTypes(projectId) {
+    const { data, error } = await db()
+        .from('custom_field_definitions')
+        .select('key, type, options')
+        .eq('project_id', projectId);
+    if (error)
+        throw error;
+    const fields = {};
+    for (const row of data ?? []) {
+        if (typeof row.key !== 'string' || typeof row.type !== 'string')
+            continue;
+        fields[row.key] = { type: row.type, options: Array.isArray(row.options) ? row.options : null };
+    }
+    return fields;
+}
+/** Contact ids matching segment rules (same semantics as the segments tools and the dashboard). */
+export async function resolveSegmentContactIds(projectId, rules) {
+    const tree = normalizeSegmentRulesToTree(rules);
+    const fieldTypes = rules.custom_property ? await loadFieldTypes(projectId) : {};
+    const q = buildSegmentBaseQuery(db(), projectId);
+    const { query: filtered, siteContactIds } = await applySegmentRules(q, rules, db(), projectId, fieldTypes);
+    if (siteContactIds && siteContactIds.length === 0)
+        return [];
+    const data = await readAllRows(filtered);
+    const contacts = data.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
+    if (tree.exclude_suppressed === false || contacts.length === 0)
+        return contacts.map((c) => String(c.id));
+    const suppressed = await readAllRows(db().from('suppressions').select('id, email').eq('project_id', projectId));
+    const suppressedEmails = new Set(suppressed.map((row) => String(row.email).toLowerCase()));
+    return contacts
+        .filter((c) => !suppressedEmails.has(String(c.email).toLowerCase()))
+        .map((c) => String(c.id));
+}
+export async function resolveSendAudience(projectId, siteId, rules, sendClass = 'broadcast') {
+    const matchedIds = await resolveSegmentContactIds(projectId, rules);
+    const onSender = new Set();
+    for (const chunk of chunkIds(matchedIds)) {
+        const rows = await readAllRows(db().from('site_subscriptions').select('contact_id').eq('site_id', siteId).eq('subscribed', true).in('contact_id', chunk), 'contact_id');
+        for (const row of rows)
+            onSender.add(String(row.contact_id));
+    }
+    const senderIds = matchedIds.filter((id) => onSender.has(id));
+    const { data: project, error: projectError } = await db()
+        .from('projects')
+        .select('marketing_consent_mode')
+        .eq('id', projectId)
+        .maybeSingle();
+    if (projectError)
+        throw projectError;
+    const heldBack = {};
+    let contactIds = senderIds;
+    if (project?.marketing_consent_mode === 'enforce' && senderIds.length > 0) {
+        const reasons = new Map();
+        for (const chunk of chunkIds(senderIds, 1000)) {
+            const { data, error } = await db().rpc('consent_reasons_for_contacts', {
+                p_project_id: projectId,
+                p_contact_ids: chunk,
+                p_send_class: sendClass,
+            });
+            if (error)
+                throw error;
+            for (const row of (data ?? [])) {
+                reasons.set(String(row.contact_id), row.reason);
+            }
+        }
+        contactIds = [];
+        for (const id of senderIds) {
+            // A contact the lookup did not return is held back, never assumed to have agreed.
+            const reason = reasons.has(id) ? reasons.get(id) : 'no_consent_basis';
+            if (reason == null)
+                contactIds.push(id);
+            else
+                heldBack[reason] = (heldBack[reason] ?? 0) + 1;
+        }
+    }
+    return { contactIds, matched: matchedIds.length, notOnSender: matchedIds.length - senderIds.length, heldBack };
+}

package/build/server.d.ts

@@ -15,5 +15,10 @@ export declare const GATEWAY_TOOL_NAMES: string[];
  * through the same proxy path as real MCP registration.
  */
 export declare function getRegisteredToolGroups(options?: ToolRegistrationOptions): ToolGroupMap;
+/**
+ * Server-level guidance every MCP client receives (#3669). Kept short: clients prepend it to the
+ * model's context on every connection.
+ */
+export declare const SENDINEL_SERVER_INSTRUCTIONS: string;
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;
 export {};

package/build/server.js

@@ -83,7 +83,7 @@ const WRITE_TOOLS = new Set([
     'add_campaign_branch', 'remove_campaign_branch', 'set_campaign_goal', 'remove_campaign_goal',
     'review_campaign_portfolio',
     'list_campaign_steps', 'update_campaign_step', 'delete_campaign_step',
-    'enroll_contact', 'enroll_segment', 'broadcast_to_segment', 'get_enrollment_status', 'clone_campaign', 'clone_sequence_template', 'generate_email',
+    'enroll_contact', 'enroll_segment', 'broadcast_to_segment', 'send_broadcast', 'get_enrollment_status', 'clone_campaign', 'clone_sequence_template', 'generate_email',
     'create_social_campaign', 'schedule_social_post',
     'create_social_post', 'update_social_post', 'delete_social_post',
     'create_draft', 'approve_draft', 'reject_draft',
@@ -300,6 +300,16 @@ function createScopeProxy(server, scopes, toolGroup) {
         },
     });
 }
+/**
+ * Server-level guidance every MCP client receives (#3669). Kept short: clients prepend it to the
+ * model's context on every connection.
+ */
+export const SENDINEL_SERVER_INSTRUCTIONS = [
+    'Sendinel runs email for this workspace: contacts, segments, campaigns, templates and sending.',
+    'To send a one-off email, use send_broadcast: call it with an audience and a brief (or html + subject), show the person the subject, recipient count and approve_url it returns, then call it again with only approval_id once they have approved.',
+    'Anything that emails real people needs a person to approve it. Never say an email was sent until the tool that sends it has succeeded.',
+    'In gateway mode, find tools with search_tools (plain words work, for example "send email" or "last campaign"), check arguments with describe_tool, then call invoke_tool.',
+].join(' ');
 export function registerAllTools(server, options) {
     const rawScopes = options?.scopes ?? [];
     if (rawScopes.includes('gateway')) {

package/build/tools/campaigns.js

@@ -12,7 +12,9 @@ import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.js';
 import { buildVoicePrompt, buildEmailSystemPrompt, deriveTemplateVariables, validateTemplate } from '../lib/voice.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
-import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
+import { approvalExcerpt, assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
+import { resolveSendAudience } from '../lib/send-audience.js';
+import { generateEmailFromBrief, parseAudienceRules } from '../lib/email-generation.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { getScheduleWindowBounds, groupScheduleByCampaign, parseFutureDate } from '../lib/schedule.js';
 import { sendEmailForSite } from '../lib/email-provider.js';
@@ -151,63 +153,6 @@ function applySegmentPaymentDateRule(query, field, rule) {
         q = q.lte(column, rule.before);
     return q;
 }
-async function getSegmentContactIds(projectId, rules) {
-    let q = db()
-        .from('subscribers')
-        .select('id, email')
-        .eq('project_id', projectId)
-        .eq('global_unsubscribed', false)
-        .is('cooled_at', null);
-    if (rules.lifecycle_stage)
-        q = q.eq('lifecycle_stage', rules.lifecycle_stage);
-    q = applySegmentPaymentRules(q, rules.payment);
-    if (rules.min_score !== undefined)
-        q = q.gte('engagement_score', rules.min_score);
-    if (rules.max_score !== undefined)
-        q = q.lte('engagement_score', rules.max_score);
-    if (rules.source)
-        q = q.eq('source', rules.source);
-    if (rules.subscribed_after)
-        q = q.gte('created_at', `${rules.subscribed_after}T00:00:00Z`);
-    if (rules.subscribed_before)
-        q = q.lte('created_at', `${rules.subscribed_before}T23:59:59Z`);
-    if (rules.has_opened === true)
-        q = q.not('last_opened_at', 'is', null);
-    if (rules.has_opened === false)
-        q = q.is('last_opened_at', null);
-    if (rules.has_clicked === true)
-        q = q.not('last_clicked_at', 'is', null);
-    if (rules.has_clicked === false)
-        q = q.is('last_clicked_at', null);
-    if (rules.tag)
-        q = q.contains('tags', [rules.tag]);
-    if (rules.site_id) {
-        const { data: subs } = await db()
-            .from('site_subscriptions')
-            .select('contact_id')
-            .eq('site_id', rules.site_id)
-            .eq('subscribed', true);
-        const siteIds = (subs ?? []).map((s) => s.contact_id);
-        if (!siteIds.length)
-            return [];
-        q = q.in('id', siteIds);
-    }
-    const { data, error } = await q;
-    if (error || !data)
-        return [];
-    let ids = data.map((c) => c.id);
-    const { data: suppressed } = await db()
-        .from('suppressions')
-        .select('email')
-        .eq('project_id', projectId);
-    if (suppressed?.length) {
-        const suppressedEmails = new Set(suppressed.map((s) => s.email));
-        ids = data
-            .filter((c) => !suppressedEmails.has(c.email))
-            .map((c) => c.id);
-    }
-    return ids;
-}
 function extractJsonObject(raw) {
     const cleaned = raw.replace(/```(?:json)?/gi, '').replace(/```/g, '').trim();
     const start = cleaned.indexOf('{');
@@ -282,6 +227,94 @@ async function validateBranchTarget(campaignId, action, targetStepId, targetCamp
     }
     return null;
 }
+/**
+ * Create, enroll and activate a one-email broadcast (#3669). Shared by broadcast_to_segment and
+ * send_broadcast so both run the same steps. Enrolls exactly the given contact ids.
+ */
+async function executeBroadcast(input) {
+    const limit = await checkPlanLimit('active_campaigns');
+    if (!limit.allowed) {
+        return { ok: false, error: `Campaign limit reached (${limit.current}/${limit.limit}). Upgrade your plan for more campaigns.`, code: 'PLAN_LIMIT' };
+    }
+    const { data: campaign, error: campaignErr } = await db()
+        .from('campaigns')
+        .insert({
+        project_id: input.projectId,
+        site_id: input.siteId,
+        segment_id: input.segmentId,
+        name: input.name,
+        type: 'broadcast',
+        status: 'draft',
+        send_at: input.sendAt,
+        send_class: input.sendClass,
+        sends_per_hour: input.sendsPerHour ?? null,
+        requires_approval: false,
+        metadata: { source: input.source, ...(input.metadata ?? {}) },
+    })
+        .select('id')
+        .single();
+    if (campaignErr || !campaign) {
+        return { ok: false, error: campaignErr?.message ?? 'Failed to create campaign', code: 'CAMPAIGN_CREATE_FAILED' };
+    }
+    const { data: step, error: stepErr } = await db()
+        .from('campaign_steps')
+        .insert({
+        campaign_id: campaign.id,
+        step_order: 0,
+        subject: input.subject,
+        body_html: input.bodyHtml,
+        body_text: input.bodyText ?? null,
+        ...(Array.isArray(input.blocks) ? { blocks: input.blocks } : {}),
+        delay_days: 0,
+        delay_hours: 0,
+    })
+        .select('id')
+        .single();
+    if (stepErr || !step) {
+        return { ok: false, error: stepErr?.message ?? 'Campaign created but failed to add broadcast step', code: 'STEP_CREATE_FAILED', campaign_id: campaign.id };
+    }
+    await recordBrandAssetUsage({
+        client: db(),
+        projectId: input.projectId,
+        source: 'campaign_step',
+        resourceId: step.id,
+        html: input.bodyHtml,
+        assetIds: input.brandAssetIds,
+    }).catch((err) => {
+        console.warn('Failed to record brand asset usage for MCP broadcast:', err);
+    });
+    const nextSendAt = input.sendAt ?? new Date().toISOString();
+    const batchSize = 500;
+    for (let i = 0; i < input.contactIds.length; i += batchSize) {
+        const batch = input.contactIds.slice(i, i + batchSize).map((contact_id) => ({
+            campaign_id: campaign.id,
+            contact_id,
+            next_send_at: nextSendAt,
+        }));
+        const { error: enrollErr } = await db()
+            .from('campaign_enrollments')
+            .upsert(batch, { onConflict: 'campaign_id,contact_id', ignoreDuplicates: true });
+        if (enrollErr) {
+            return { ok: false, error: enrollErr.message, code: 'ENROLLMENT_FAILED', campaign_id: campaign.id, enrolled_before_failure: i };
+        }
+    }
+    const { error: activateErr } = await db()
+        .from('campaigns')
+        .update({ status: 'active', total_enrolled: input.contactIds.length, updated_at: new Date().toISOString() })
+        .eq('id', campaign.id)
+        .eq('project_id', input.projectId);
+    if (activateErr) {
+        return { ok: false, error: activateErr.message, code: 'ACTIVATION_FAILED', campaign_id: campaign.id, enrolled: input.contactIds.length };
+    }
+    return { ok: true, campaignId: campaign.id, stepId: step.id, enrolled: input.contactIds.length, nextSendAt };
+}
+function heldBackLines(audience) {
+    return {
+        matched: audience.matched,
+        not_signed_up_for_sender: audience.notOnSender,
+        held_back_by_consent: audience.heldBack,
+    };
+}
 export function registerCampaignTools(server) {
     server.registerTool('review_campaign_portfolio', {
         title: 'Review Campaign Portfolio',
@@ -569,7 +602,17 @@ export function registerCampaignTools(server) {
                 if (!decision.allowed)
                     return txt(decision.reason ?? 'This channel cannot request this action.');
                 if (decision.tier !== 'autonomous') {
-                    const approval = await requestApproval('update_campaign_status', approvalParams, undefined, channelContext);
+                    const { data: camp } = await db()
+                        .from('campaigns')
+                        .select('name, total_enrolled, trigger_event_name, trigger_tag')
+                        .eq('id', campaign_id)
+                        .eq('project_id', getProjectId())
+                        .maybeSingle();
+                    const approval = await requestApproval('update_campaign_status', approvalParams, undefined, channelContext, {
+                        campaign_name: camp?.name ?? null,
+                        enrolled: typeof camp?.total_enrolled === 'number' ? camp.total_enrolled : null,
+                        trigger: camp?.trigger_event_name ?? (camp?.trigger_tag ? `tag ${camp.trigger_tag}` : null),
+                    });
                     return j(approval);
                 }
             }
@@ -824,7 +867,16 @@ export function registerCampaignTools(server) {
             ...(segment.rules ?? {}),
             ...(segment.site_id ? { site_id: segment.site_id } : {}),
         };
-        const contactIds = await getSegmentContactIds(projectId, rules);
+        // #3669: the same audience rules as send_broadcast and the dashboard: paged, signed up to this
+        // sender, consent gate applied. The count shown is the count enrolled.
+        let audience;
+        try {
+            audience = await resolveSendAudience(projectId, site_id, rules);
+        }
+        catch (error) {
+            return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
+        }
+        const contactIds = audience.contactIds;
         if (!confirmed) {
             return j({
                 confirmation_required: true,
@@ -838,16 +890,18 @@ export function registerCampaignTools(server) {
                     sends_per_hour: sends_per_hour ?? null,
                 },
                 matching_contacts: contactIds.length,
+                audience: heldBackLines(audience),
                 will_send_at: 'immediately',
                 message: `Broadcast "${campaignName}" will enroll ${contactIds.length} eligible contact(s) from segment "${segment.name}" and activate immediately. Call again with confirmed=true to proceed.`,
             });
         }
         if (contactIds.length === 0) {
             return j({
-                error: 'No eligible contacts match this segment.',
+                error: 'Nobody in this segment can get email from this sender right now.',
                 code: 'EMPTY_SEGMENT',
                 segment_id,
                 site_id,
+                audience: heldBackLines(audience),
             });
         }
         const channelContext = currentChannelContext();
@@ -856,7 +910,12 @@ export function registerCampaignTools(server) {
             return txt(decision.reason ?? 'This channel cannot request this action.');
         if (decision.tier !== 'autonomous') {
             if (!approval_id) {
-                const approval = await requestApproval('broadcast_to_segment', approvalParams, undefined, channelContext);
+                const approval = await requestApproval('broadcast_to_segment', approvalParams, undefined, channelContext, {
+                    subject,
+                    segment_name: segment.name,
+                    recipient_count: contactIds.length,
+                    body_excerpt: approvalExcerpt(body_html),
+                });
                 return j(approval);
             }
             const check = await checkApproval(approval_id, { consume: true, action: 'broadcast_to_segment', params: approvalParams });
@@ -864,98 +923,28 @@ export function registerCampaignTools(server) {
                 return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
             }
         }
-        const limit = await checkPlanLimit('active_campaigns');
-        if (!limit.allowed) {
-            return j({
-                error: `Campaign limit reached (${limit.current}/${limit.limit}). Upgrade your plan for more campaigns.`,
-                code: 'PLAN_LIMIT',
-            });
-        }
-        const { data: campaign, error: campaignErr } = await db()
-            .from('campaigns')
-            .insert({
-            project_id: projectId,
-            site_id,
-            segment_id,
+        const executed = await executeBroadcast({
+            projectId,
+            siteId: site_id,
+            segmentId: segment_id,
             name: campaignName,
-            type: 'broadcast',
-            status: 'draft',
-            sends_per_hour: sends_per_hour ?? null,
-            requires_approval: false,
-            metadata: { source: 'mcp_broadcast_to_segment' },
-        })
-            .select('id')
-            .single();
-        if (campaignErr || !campaign) {
-            return j({ error: campaignErr?.message ?? 'Failed to create campaign', code: 'CAMPAIGN_CREATE_FAILED' });
-        }
-        const { data: step, error: stepErr } = await db()
-            .from('campaign_steps')
-            .insert({
-            campaign_id: campaign.id,
-            step_order: 0,
             subject,
-            body_html,
-            body_text: body_text ?? null,
-            delay_days: 0,
-            delay_hours: 0,
-        })
-            .select('id')
-            .single();
-        if (stepErr || !step) {
-            return j({
-                error: stepErr?.message ?? 'Campaign created but failed to add broadcast step',
-                code: 'STEP_CREATE_FAILED',
-                campaign_id: campaign.id,
-            });
-        }
-        await recordBrandAssetUsage({
-            client: db(),
-            projectId,
-            source: 'campaign_step',
-            resourceId: step.id,
-            html: body_html,
-            assetIds: brand_asset_ids,
-        }).catch((err) => {
-            console.warn('Failed to record brand asset usage for MCP broadcast:', err);
+            bodyHtml: body_html,
+            bodyText: body_text ?? null,
+            sendsPerHour: sends_per_hour ?? null,
+            contactIds,
+            sendAt: null,
+            sendClass: 'broadcast',
+            brandAssetIds: brand_asset_ids,
+            source: 'mcp_broadcast_to_segment',
         });
-        const sendAt = new Date().toISOString();
-        const batchSize = 500;
-        for (let i = 0; i < contactIds.length; i += batchSize) {
-            const batch = contactIds.slice(i, i + batchSize).map((contact_id) => ({
-                campaign_id: campaign.id,
-                contact_id,
-                next_send_at: sendAt,
-            }));
-            const { error: enrollErr } = await db()
-                .from('campaign_enrollments')
-                .upsert(batch, { onConflict: 'campaign_id,contact_id', ignoreDuplicates: true });
-            if (enrollErr) {
-                return j({
-                    error: enrollErr.message,
-                    code: 'ENROLLMENT_FAILED',
-                    campaign_id: campaign.id,
-                    enrolled_before_failure: i,
-                });
-            }
-        }
-        const { error: activateErr } = await db()
-            .from('campaigns')
-            .update({
-            status: 'active',
-            total_enrolled: contactIds.length,
-            updated_at: new Date().toISOString(),
-        })
-            .eq('id', campaign.id)
-            .eq('project_id', projectId);
-        if (activateErr) {
-            return j({
-                error: activateErr.message,
-                code: 'ACTIVATION_FAILED',
-                campaign_id: campaign.id,
-                enrolled: contactIds.length,
-            });
+        if (!executed.ok) {
+            const { ok: _ok, ...failure } = executed;
+            return j(failure);
         }
+        const campaign = { id: executed.campaignId };
+        const step = { id: executed.stepId };
+        const sendAt = executed.nextSendAt;
         await logAudit({
             action: 'campaign.broadcast_to_segment',
             resourceType: 'campaign',
@@ -985,6 +974,226 @@ export function registerCampaignTools(server) {
             message: `Broadcast "${campaignName}" is active with ${contactIds.length} contact(s) enrolled for immediate sending.`,
         });
     });
+    server.registerTool('send_broadcast', {
+        title: 'Send Broadcast',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: 'Send a one-off email in two calls. Call 1: give an audience (audience in plain words, or segment_id) and content (brief for an AI draft, or html + subject); it returns the finished email, the recipient count, the sender and an approval_id, and sends nothing. A person approves it (approve_url works on a phone). Call 2: pass ONLY approval_id; it sends exactly what was approved. Use this for "send an email to…", newsletters, announcements.',
+        inputSchema: {
+            audience: z.string().min(3).max(500).optional().describe('Who gets it, in plain words (for example "trial users who have not opened anything"). Use this or segment_id.'),
+            segment_id: z.string().uuid().optional().describe('A saved segment. Use this or audience.'),
+            brief: z.string().min(10).max(4000).optional().describe('What the email should say; Sendinel drafts it in your brand voice. Use this or html.'),
+            html: z.string().min(1).optional().describe('A finished HTML body. Requires subject. Use this or brief.'),
+            subject: z.string().min(1).max(300).optional().describe('Subject line. Required with html; overrides the drafted subject with brief.'),
+            body_text: z.string().optional().describe('Plain-text version for html. Derived from the HTML when omitted.'),
+            site_id: z.string().uuid().optional().describe('Sender. Optional when the project has exactly one sender.'),
+            send_at: z.string().datetime().optional().describe('Future ISO time to send. Omit to send right after approval.'),
+            name: z.string().min(1).max(200).optional().describe('Campaign name. Defaults from the subject.'),
+            send_class: z.enum(['broadcast', 'product']).optional().describe('broadcast (marketing, default) or product (account and onboarding email). Decides which consent rules apply.'),
+            brand_asset_ids: z.array(z.string().uuid()).optional().describe('Brand media assets used in the body.'),
+            approval_id: z.string().uuid().optional().describe('Call 2 only: the approved approval_id from call 1. Pass nothing else.'),
+        },
+    }, async (args) => {
+        const projectId = getProjectId();
+        const { approval_id } = args;
+        // ── Call 2: execute exactly the approved, frozen payload. Nothing else is trusted. ──
+        if (approval_id) {
+            const extras = Object.entries(args).filter(([key, value]) => key !== 'approval_id' && value !== undefined).map(([key]) => key);
+            if (extras.length) {
+                return j({ error: `Call send_broadcast with only approval_id to send. Remove: ${extras.join(', ')}. To change anything, start over without approval_id.`, code: 'APPROVAL_CALL_TAKES_ONLY_APPROVAL_ID' });
+            }
+            const { data: row, error: rowErr } = await db()
+                .from('action_approvals')
+                .select('params')
+                .eq('id', approval_id)
+                .eq('project_id', projectId)
+                .eq('action', 'send_broadcast')
+                .maybeSingle();
+            if (rowErr)
+                return j({ error: rowErr.message, code: 'APPROVAL_LOOKUP_FAILED' });
+            if (!row)
+                return txt(`Approval ${approval_id} is not_found. Request a new approval.`);
+            const stored = (row.params ?? {});
+            const check = await checkApproval(approval_id, { consume: true, action: 'send_broadcast', params: stored });
+            if (!check.approved) {
+                return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
+            }
+            const payload = (stored.payload ?? {});
+            const contactIds = Array.isArray(payload.contact_ids) ? payload.contact_ids.map(String) : [];
+            if (payload.send_at && new Date(payload.send_at).getTime() <= Date.now()) {
+                // An approved future time that has now passed: send right away rather than silently skip.
+                payload.send_at = null;
+            }
+            const executed = await executeBroadcast({
+                projectId,
+                siteId: String(payload.site_id),
+                segmentId: payload.segment_id ?? null,
+                name: String(payload.name),
+                subject: String(payload.subject),
+                bodyHtml: String(payload.body_html),
+                bodyText: payload.body_text ?? null,
+                blocks: Array.isArray(payload.blocks) ? payload.blocks : null,
+                contactIds,
+                sendAt: payload.send_at ?? null,
+                sendClass: payload.send_class === 'product' ? 'product' : 'broadcast',
+                brandAssetIds: Array.isArray(payload.brand_asset_ids) ? payload.brand_asset_ids : undefined,
+                source: 'mcp_send_broadcast',
+                metadata: { approval_id, ...(payload.rules ? { audience_rules: payload.rules } : {}) },
+            });
+            if (!executed.ok) {
+                const { ok: _ok, ...failure } = executed;
+                return j(failure);
+            }
+            await logAudit({
+                action: 'campaign.send_broadcast',
+                resourceType: 'campaign',
+                resourceId: executed.campaignId,
+                details: { approval_id, decided_by: check.decided_by ?? null, site_id: payload.site_id, segment_id: payload.segment_id ?? null, contacts_enrolled: executed.enrolled, send_at: payload.send_at ?? null, source: 'mcp' },
+            }).catch(() => { });
+            fireWebhookEvent('campaign.activated', {
+                campaign_id: executed.campaignId,
+                campaign_name: payload.name,
+                type: 'broadcast',
+                contacts_enrolled: executed.enrolled,
+                steps: 1,
+            }).catch(() => { });
+            return j({
+                campaign_id: executed.campaignId,
+                step_id: executed.stepId,
+                status: 'active',
+                contacts_enrolled: executed.enrolled,
+                send_at: payload.send_at ?? 'now',
+                message: payload.send_at
+                    ? `Scheduled: "${payload.subject}" goes to ${executed.enrolled} people at ${payload.send_at}.`
+                    : `Sending: "${payload.subject}" is going to ${executed.enrolled} people now. Delivery happens over the next few minutes; check the campaign for results.`,
+            });
+        }
+        // ── Call 1: resolve, render, count, request approval. Sends nothing. ──
+        const { audience, segment_id, brief, html, subject, body_text, site_id, send_at, name, send_class, brand_asset_ids } = args;
+        if (Boolean(audience) === Boolean(segment_id))
+            return j({ error: 'Give exactly one of audience or segment_id.', code: 'AUDIENCE_REQUIRED' });
+        if (Boolean(brief) === Boolean(html))
+            return j({ error: 'Give exactly one of brief or html.', code: 'CONTENT_REQUIRED' });
+        if (html && !subject)
+            return j({ error: 'subject is required with html.', code: 'SUBJECT_REQUIRED' });
+        let sendAt = null;
+        if (send_at) {
+            const parsed = parseFutureDate(send_at, 'send_at');
+            if ('error' in parsed)
+                return j({ error: parsed.error, code: 'INVALID_SEND_AT' });
+            sendAt = parsed.scheduledAt;
+        }
+        // Sender: the given one, or the only one. Never guessed between several.
+        const { data: sites, error: sitesErr } = await db()
+            .from('sites')
+            .select('id, name, from_email')
+            .eq('project_id', projectId);
+        if (sitesErr)
+            return j({ error: sitesErr.message, code: 'SITE_LOOKUP_FAILED' });
+        const site = site_id ? (sites ?? []).find((s) => s.id === site_id) : (sites?.length === 1 ? sites[0] : null);
+        if (!site) {
+            return j({
+                error: site_id ? 'Site not found in this project.' : 'This project has more than one sender. Pass site_id.',
+                code: site_id ? 'SITE_NOT_FOUND' : 'SITE_REQUIRED',
+                sites: (sites ?? []).map((s) => ({ id: s.id, name: s.name, from_email: s.from_email })),
+            });
+        }
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if ((audience || brief) && !apiKey)
+            return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_NOT_CONFIGURED' });
+        const anthropic = apiKey ? new Anthropic({ apiKey }) : null;
+        let rules;
+        let segmentName;
+        if (segment_id) {
+            const { data: segment, error: segmentErr } = await db()
+                .from('segments')
+                .select('id, name, rules, site_id')
+                .eq('id', segment_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (segmentErr)
+                return j({ error: segmentErr.message, code: 'SEGMENT_LOOKUP_FAILED' });
+            if (!segment)
+                return j({ error: 'Segment not found', code: 'SEGMENT_NOT_FOUND' });
+            rules = { ...(segment.rules ?? {}), ...(segment.site_id ? { site_id: segment.site_id } : {}) };
+            segmentName = segment.name;
+        }
+        else {
+            try {
+                rules = await parseAudienceRules(anthropic, audience);
+            }
+            catch (error) {
+                return j({ error: error instanceof Error ? error.message : String(error), code: 'AUDIENCE_NOT_UNDERSTOOD' });
+            }
+            segmentName = audience;
+        }
+        const sendClass = send_class === 'product' ? 'product' : 'broadcast';
+        let resolved;
+        try {
+            resolved = await resolveSendAudience(projectId, site.id, rules, sendClass);
+        }
+        catch (error) {
+            return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
+        }
+        if (resolved.contactIds.length === 0) {
+            return j({ error: 'Nobody in this audience can get this email from this sender.', code: 'EMPTY_AUDIENCE', audience: heldBackLines(resolved), rules });
+        }
+        let content;
+        if (brief) {
+            try {
+                const generated = await generateEmailFromBrief(anthropic, projectId, site.id, brief);
+                content = { subject: subject ?? generated.subject, body_html: generated.body_html, body_text: generated.body_text, blocks: generated.blocks };
+            }
+            catch (error) {
+                return j({ error: error instanceof Error ? error.message : String(error), code: 'DRAFT_FAILED' });
+            }
+        }
+        else {
+            content = { subject: subject, body_html: html, body_text: body_text ?? approvalExcerpt(html, 100000), blocks: null };
+        }
+        const campaignName = name ?? `Broadcast - ${content.subject.slice(0, 120)}`;
+        const payload = {
+            site_id: site.id,
+            segment_id: segment_id ?? null,
+            rules: segment_id ? null : rules,
+            subject: content.subject,
+            body_html: content.body_html,
+            body_text: content.body_text,
+            blocks: content.blocks,
+            name: campaignName,
+            send_at: sendAt,
+            send_class: sendClass,
+            brand_asset_ids: brand_asset_ids ?? null,
+            // Frozen at approval time: the people approved are the people enrolled.
+            contact_ids: resolved.contactIds,
+        };
+        const approvalParams = { payload };
+        const channelContext = currentChannelContext();
+        const decision = assertChannelCanExecute('send_broadcast', approvalParams, channelContext);
+        if (!decision.allowed)
+            return txt(decision.reason ?? 'This channel cannot request this action.');
+        const approval = await requestApproval('send_broadcast', approvalParams, undefined, channelContext, {
+            subject: content.subject,
+            segment_name: segment_id ? segmentName : null,
+            audience_label: segment_id ? null : `"${segmentName}"`,
+            recipient_count: resolved.contactIds.length,
+            body_excerpt: approvalExcerpt(content.body_html),
+            send_at: sendAt,
+        });
+        return j({
+            ...approval,
+            rendered: { subject: content.subject, body_html: content.body_html, body_text: content.body_text },
+            recipient_count: resolved.contactIds.length,
+            audience: { label: segmentName, segment_id: segment_id ?? null, ...heldBackLines(resolved) },
+            site: { id: site.id, name: site.name, from_email: site.from_email },
+            send_at: sendAt ?? 'right after approval',
+            next: 'Show the user the subject, recipient count and approve_url. After a person approves, call send_broadcast with only approval_id. Do not say it was sent before that call succeeds.',
+        });
+    });
     server.registerTool('clone_campaign', {
         title: 'Clone Campaign',
         annotations: {

package/build/tools/gateway.d.ts

@@ -3,4 +3,15 @@ export interface GatewayOptions {
     scopes?: string[];
     toolGroups?: string[];
 }
+/**
+ * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
+ * "last campaign" (#3669). Matched alongside name, group and description.
+ */
+export declare const INTENT_ALIASES: Record<string, string[]>;
+/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+export declare function matchesToolQuery(entry: {
+    name: string;
+    group: string;
+    description: string;
+}, query: string): boolean;
 export declare function registerGatewayTools(server: McpServer, options: GatewayOptions): void;

package/build/tools/gateway.js

@@ -9,6 +9,29 @@ const notFound = (message) => ({
     isError: true,
     content: [{ type: 'text', text: message }],
 });
+/**
+ * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
+ * "last campaign" (#3669). Matched alongside name, group and description.
+ */
+export const INTENT_ALIASES = {
+    send_broadcast: ['send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email'],
+    list_campaigns: ['last campaign', 'latest campaign', 'recent campaign', 'my campaigns'],
+    get_campaign: ['last campaign', 'campaign details', 'campaign results'],
+    create_campaign: ['welcome', 'welcome email', 'onboarding', 'drip', 'sequence', 'triggered email'],
+    add_campaign_step: ['welcome', 'onboarding', 'follow up email', 'next email in sequence'],
+};
+/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+export function matchesToolQuery(entry, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return true;
+    const haystack = [entry.name, entry.name.replace(/_/g, ' '), entry.group, entry.description, ...(INTENT_ALIASES[entry.name] ?? [])]
+        .join(' \n ')
+        .toLowerCase();
+    if (haystack.includes(q))
+        return true;
+    return q.split(/\s+/).filter(Boolean).every((token) => haystack.includes(token));
+}
 async function buildCatalog(options) {
     const innerServer = new McpServer({ name: 'sendinel-gateway-inner', version: '1.0.0' });
     registerAllTools(innerServer, { scopes: options.scopes, toolGroups: options.toolGroups });
@@ -39,7 +62,7 @@ export function registerGatewayTools(server, options) {
         description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Call describe_tool for the full input schema before invoke_tool.',
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
-            query: z.string().optional().describe('Keyword to match against tool name, group, or description'),
+            query: z.string().optional().describe('Words to match against tool name, group, description, or common phrasing (for example "send email")'),
             group: z.string().optional().describe('Restrict results to one tool group, for example campaigns'),
         },
     }, async ({ query, group }) => {
@@ -49,11 +72,7 @@ export function registerGatewayTools(server, options) {
         const results = catalog.entries.filter((tool) => {
             if (requestedGroup && tool.group !== requestedGroup)
                 return false;
-            if (!q)
-                return true;
-            return (tool.name.toLowerCase().includes(q) ||
-                tool.group.toLowerCase().includes(q) ||
-                tool.description.toLowerCase().includes(q));
+            return matchesToolQuery(tool, q);
         });
         return jsonResult({
             tools: results.map(({ name, group, description }) => ({ name, group, description })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",