@sendinel/mcp-server 1.0.3 → 1.0.5

package/build/tools/contacts.js

@@ -1,17 +1,96 @@
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
 import { z } from 'zod';
-import { db } from '../db.js';
+import { db, projectClientForWriteback } from '../db.js';
 import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.js';
 import { logConsent, logAudit } from '../audit.js';
-import { requestApproval, checkApproval } from '../lib/action-approvals.js';
+import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
 import { decrypt } from '../crypto.js';
 import { normalizeActiveCampaignAccountUrl } from '../lib/url-validation.js';
 import Anthropic from '@anthropic-ai/sdk';
 import { getAnthropicModelId } from '../anthropic-model.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+async function byodWritebackClient(projectId) {
+    const customer = projectClientForWriteback();
+    if (!customer)
+        return null;
+    const { data } = await db()
+        .from('projects')
+        .select('connector_type, connector_view_installed')
+        .eq('id', projectId)
+        .maybeSingle();
+    return data?.connector_type === 'byod' && data.connector_view_installed === true ? customer : null;
+}
+async function resolveMcpByodTarget(projectId, contact, customer) {
+    let sourceId = typeof contact.custom_properties?.db_import_source_id === 'string' ? contact.custom_properties.db_import_source_id : null;
+    if (sourceId?.startsWith('sendinel:'))
+        return { kind: 'contact', sourceId, rowId: sourceId.slice('sendinel:'.length) };
+    if (sourceId)
+        return { kind: 'state', sourceId };
+    const inserted = await customer
+        .schema('email')
+        .from('subscribers')
+        .insert({
+        project_id: projectId,
+        email: contact.email,
+        first_name: contact.first_name ?? null,
+        last_name: contact.last_name ?? null,
+        source: 'sendinel',
+        custom_properties: contact.custom_properties ?? {},
+    })
+        .select('id')
+        .single();
+    let rowId = inserted.data?.id;
+    if (inserted.error?.code === '23505') {
+        const existing = await customer.schema('email').from('subscribers').select('id').eq('project_id', projectId).eq('email', contact.email).maybeSingle();
+        rowId = existing.data?.id;
+    }
+    else if (inserted.error) {
+        throw inserted.error;
+    }
+    if (!rowId)
+        return null;
+    sourceId = `sendinel:${rowId}`;
+    await db().from('subscribers').update({
+        custom_properties: {
+            ...(contact.custom_properties ?? {}),
+            db_import_source_id: sourceId,
+            db_import_source_table: 'email.subscribers',
+        },
+    }).eq('project_id', projectId).eq('id', contact.id);
+    return { kind: 'contact', sourceId, rowId };
+}
+async function writeBackMcpContact(projectId, contact, patch) {
+    try {
+        const customer = await byodWritebackClient(projectId);
+        if (!customer || !contact?.id || !contact?.email)
+            return;
+        const target = await resolveMcpByodTarget(projectId, contact, customer);
+        if (!target)
+            return;
+        const customPatch = patch.custom_properties;
+        if (target.kind === 'state') {
+            const statePatch = Object.fromEntries(Object.entries(patch).filter(([key]) => !['email', 'first_name', 'last_name', 'company_id'].includes(key)));
+            if (customPatch) {
+                const existing = await customer.schema('public').from('sendinel_subscriber_state').select('custom_properties').eq('source_id', target.sourceId).maybeSingle();
+                statePatch.custom_properties = { ...(existing.data?.custom_properties ?? {}), ...customPatch };
+            }
+            await customer.schema('public').from('sendinel_subscriber_state').upsert({ source_id: target.sourceId, ...statePatch, updated_at: new Date().toISOString() }, { onConflict: 'source_id' });
+            return;
+        }
+        const update = { ...patch, updated_at: new Date().toISOString() };
+        if (customPatch) {
+            const existing = await customer.schema('email').from('subscribers').select('custom_properties').eq('id', target.rowId).maybeSingle();
+            update.custom_properties = { ...(existing.data?.custom_properties ?? {}), ...customPatch };
+        }
+        await customer.schema('email').from('subscribers').update(update).eq('id', target.rowId);
+    }
+    catch (error) {
+        logAudit({ action: 'byod_writeback_failed', resourceType: 'contact', resourceId: contact?.id, details: { email: contact?.email, error: error instanceof Error ? error.message : String(error) } });
+    }
+}
 function daysAgo(days) {
     return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
 }
@@ -248,6 +327,13 @@ async function exportSubscriberData(projectId, contactId) {
 }
 export function registerContactTools(server) {
     server.registerTool('get_subscriber_timeline', {
+        title: 'Get Subscriber Timeline',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get a merged activity timeline for a contact.',
         inputSchema: { subscriber_id: z.string().uuid(), limit: z.number().int().min(1).max(100).optional().default(50) },
     }, async ({ subscriber_id, limit = 50 }) => {
@@ -270,15 +356,29 @@ export function registerContactTools(server) {
         return j({ events: timeline });
     });
     server.registerTool('get_hygiene_config', {
+        title: 'Get Hygiene Config',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get list hygiene automation config.',
         inputSchema: {},
     }, async () => {
-        const { data, error } = await db().from('list_hygiene_config').select('*').eq('project_id', getProjectId()).maybeSingle();
+        const { data, error } = await db().from('hygiene_config').select('*').eq('project_id', getProjectId()).maybeSingle();
         if (error)
             return j({ error: error.message });
-        return j(data ?? { enabled: false, inactive_days: 90, action: 'tag', tag_name: 'cold', suppress_after_days: 180, last_run_at: null });
+        return j(data ?? { enabled: false, inactive_days: 90, action: 'tag', tag_name: 'cold', suppress_after_days: 180, activity_property: null, last_run_at: null });
     });
     server.registerTool('update_hygiene_config', {
+        title: 'Update Hygiene Config',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Update list hygiene automation config.',
         inputSchema: {
             enabled: z.boolean().optional(),
@@ -286,14 +386,32 @@ export function registerContactTools(server) {
             action: z.enum(['tag', 'suppress', 'tag_and_suppress']).optional(),
             tag_name: z.string().optional(),
             suppress_after_days: z.number().int().min(1).optional(),
+            activity_property: z.string().optional(),
         },
     }, async (config) => {
-        const { error } = await db().from('list_hygiene_config').upsert({ project_id: getProjectId(), ...config, updated_at: new Date().toISOString() }, { onConflict: 'project_id' });
+        const activityProperty = typeof config.activity_property === 'string' && config.activity_property.trim()
+            ? config.activity_property.trim().slice(0, 128)
+            : null;
+        const row = {
+            project_id: getProjectId(),
+            ...config,
+            updated_at: new Date().toISOString(),
+        };
+        if (Object.prototype.hasOwnProperty.call(config, 'activity_property'))
+            row.activity_property = activityProperty;
+        const { error } = await db().from('hygiene_config').upsert(row, { onConflict: 'project_id' });
         if (error)
             return j({ error: error.message });
         return j({ updated: true });
     });
     server.registerTool('run_list_hygiene', {
+        title: 'Run List Hygiene',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Run list hygiene immediately for the project.',
         inputSchema: {},
     }, async () => {
@@ -307,6 +425,13 @@ export function registerContactTools(server) {
         return j({ tagged: ids.length, suppressed: 0, skipped: 0 });
     });
     server.registerTool('list_hygiene_audit', {
+        title: 'List Hygiene Audit',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Audit list engagement health and identify sunset candidates while excluding active paying customers.',
         inputSchema: {
             siteId: z.string().uuid(),
@@ -371,13 +496,21 @@ export function registerContactTools(server) {
         });
     });
     server.registerTool('list_win_back_draft', {
+        title: 'List Win Back Draft',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: 'Draft a human-approved win-back email for dormant or sunset contacts. Does not enqueue or send.',
         inputSchema: {
             siteId: z.string().uuid(),
             segmentId: z.string().uuid().optional(),
             cohort: z.enum(['dormant', 'sunset_candidates']).optional().default('dormant'),
+            draftStyle: z.enum(['short_question', 'full_recap']).optional().default('short_question'),
         },
-    }, async ({ siteId, segmentId, cohort = 'dormant' }) => {
+    }, async ({ siteId, segmentId, cohort = 'dormant', draftStyle = 'short_question' }) => {
         const projectId = getProjectId();
         const [{ data: site }, { data: subs }] = await Promise.all([
             db().from('sites').select('id, name, sending_domain, brand_voice, projects(org_id, organizations(brand_settings))').eq('id', siteId).eq('project_id', projectId).maybeSingle(),
@@ -408,10 +541,19 @@ export function registerContactTools(server) {
         if (!apiKey)
             return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_UNAVAILABLE' });
         const client = new Anthropic({ apiKey });
+        // Short single-question re-engagement copy outperforms full recaps in
+        // practice (median document view time ~17-32s -- see #1986) -- default to
+        // it, same style contract as buildCertificateEmailUser's reengagement
+        // branch, but this tool builds its own prompt directly rather than going
+        // through voice.ts.
+        const styleInstruction = draftStyle === 'full_recap'
+            ? 'Style: FULL RECAP -- briefly restate the offer/value before the CTA.'
+            : 'Style: SHORT SINGLE QUESTION (default) -- 2-3 short sentences total, ending in ONE direct, easy-to-answer question. Do not recap the full offer, list features, or repeat prior email content. Assume the reader skims in under 30 seconds.';
         const prompt = `Draft a win-back email for ${site.name}.
 Cohort: ${cohort}
 Sample contacts: ${JSON.stringify((sample ?? []).slice(0, 10))}
 Brand settings: ${JSON.stringify({ site_brand_voice: site.brand_voice, org_brand_settings: site.projects?.organizations?.brand_settings })}
+${styleInstruction}
 
 Return JSON only with subject, preview_text, body_html, cta_text, reasoning.
 Requirements: urgency without desperation, acknowledge the gap, one clear CTA, visible one-click unsubscribe link in body using {{unsubscribe_url}}, no auto-send language.`;
@@ -431,6 +573,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             site_id: siteId,
             segment_id: segmentId ?? null,
             cohort,
+            draft_style: draftStyle,
             sample_size: sample?.length ?? 0,
             draft,
             auto_enqueued: false,
@@ -438,6 +581,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         });
     });
     server.registerTool('list_subscribers', {
+        title: 'List Subscribers',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List contacts, optionally filtered by site and/or search term',
         inputSchema: {
             site_id: z.string().uuid().optional(),
@@ -490,6 +640,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('list_companies', {
+        title: 'List Companies',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List linked companies for the current project with rolled-up contact engagement metrics.',
         inputSchema: {
             search: z.string().optional().describe('Partial match on company name or domain'),
@@ -535,6 +692,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         })));
     });
     server.registerTool('add_subscriber', {
+        title: 'Add Subscriber',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Add a contact and subscribe them to a site',
         inputSchema: {
             email: z.string().email(),
@@ -612,14 +776,23 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (needsConfirm) {
             // Create opt-in token (confirmation email must be sent externally in MCP context)
             await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
+            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
             logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
             return { content: [{ type: 'text', text: JSON.stringify({ ...contact, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.' }, null, 2) }] };
         }
+        await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
         logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
         logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
         return { content: [{ type: 'text', text: JSON.stringify(contact, null, 2) }] };
     });
     server.registerTool('import_subscribers', {
+        title: 'Import Subscribers',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Bulk import contacts and subscribe them to a site. Max 200 per call.',
         inputSchema: {
             contacts: z.array(z.object({
@@ -693,7 +866,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         const { data: upserted, error: uErr } = await db()
             .from('subscribers')
             .upsert(rows, { onConflict: 'project_id,email', ignoreDuplicates: false })
-            .select('id, email');
+            .select('id, email, first_name, last_name, custom_properties');
         if (uErr)
             return { content: [{ type: 'text', text: `Error: ${uErr.message}` }] };
         const contactRows = upserted ?? [];
@@ -701,11 +874,19 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (subRows.length) {
             await db().from('site_subscriptions').upsert(subRows, { onConflict: 'contact_id,site_id', ignoreDuplicates: true });
         }
+        await Promise.allSettled(contactRows.map((contact) => writeBackMcpContact(projectId, contact, { email: contact.email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null })));
         const created = contactRows.filter((c) => !existingEmails.has(c.email)).length;
         const updated = contactRows.length - created;
         return { content: [{ type: 'text', text: JSON.stringify({ created, updated, total: contactRows.length }, null, 2) }] };
     });
     server.registerTool('unsubscribe_subscriber', {
+        title: 'Unsubscribe Subscriber',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Globally unsubscribe a contact from all sites',
         inputSchema: {
             email: z.string().email(),
@@ -717,7 +898,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .update({ global_unsubscribed: true, global_unsubscribed_at: now })
             .eq('project_id', getProjectId())
             .eq('email', email)
-            .select('id, email')
+            .select('id, email, first_name, last_name, custom_properties')
             .single();
         if (error)
             return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
@@ -730,10 +911,18 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .eq('subscribed', true);
             logConsent({ contactId: data.id, action: 'revoke', consentType: 'email_marketing', source: 'mcp_unsubscribe' });
             logAudit({ action: 'contact.unsubscribed', resourceType: 'contact', resourceId: data.id, details: { email } });
+            await writeBackMcpContact(getProjectId(), data, { global_unsubscribed: true, custom_properties: { global_unsubscribed_at: now } });
         }
         return { content: [{ type: 'text', text: JSON.stringify({ unsubscribed: true, ...data }, null, 2) }] };
     });
     server.registerTool('list_email_log', {
+        title: 'List Email Log',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Recent email sends with status, filterable by site and/or recipient',
         inputSchema: {
             site_id: z.string().uuid().optional(),
@@ -760,6 +949,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('list_suppressions', {
+        title: 'List Suppressions',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List suppressed email addresses (hard bounces, complaints, manual blocks)',
         inputSchema: {
             limit: z.number().int().min(1).max(500).optional().default(100),
@@ -780,6 +976,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('add_suppression', {
+        title: 'Add Suppression',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Manually add an email to the suppression list',
         inputSchema: {
             email: z.string().email(),
@@ -797,6 +1000,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('list_subscribers_by_segment', {
+        title: 'List Subscribers By Segment',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List contacts filtered by engagement score range and/or lifecycle stage. Useful for building re-engagement campaigns or identifying high-value contacts.',
         inputSchema: {
             lifecycle_stage: z.enum(['new', 'active', 'cooling', 'cold', 'churned', 'lead', 'trial', 'customer', 'win-back']).optional(),
@@ -853,6 +1063,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('update_subscriber', {
+        title: 'Update Subscriber',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Update a contact\'s email, name, tags, or custom properties',
         inputSchema: {
             contact_id: z.string().uuid(),
@@ -863,7 +1080,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             company_name: z.string().nullable().optional(),
             company_domain: z.string().nullable().optional(),
             tags: z.array(z.string()).optional(),
-            custom_properties: z.record(z.unknown()).optional().describe('Merged into existing custom_properties'),
+            custom_properties: z.record(z.string(), z.unknown()).optional().describe('Merged into existing custom_properties'),
         },
     }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties }) => {
         const projectId = getProjectId();
@@ -925,9 +1142,23 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .single();
         if (error)
             return txt(`Error: ${error.message}`);
+        await writeBackMcpContact(projectId, data, {
+            ...(updates.email !== undefined ? { email: updates.email } : {}),
+            ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
+            ...(updates.last_name !== undefined ? { last_name: updates.last_name } : {}),
+            ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
+            ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
+        });
         return j(data);
     });
     server.registerTool('get_subscriber', {
+        title: 'Get Subscriber',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get full contact details including site subscriptions, by ID or email',
         inputSchema: {
             contact_id: z.string().uuid().optional(),
@@ -952,6 +1183,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j(data);
     });
     server.registerTool('enrich_subscriber', {
+        title: 'Enrich Subscriber',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: 'Enrich a subscriber from a connected CRM/ESP provider and merge provider metadata plus company info when available.',
         inputSchema: {
             contact_id: z.string().uuid(),
@@ -1013,6 +1251,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j({ contact: updated, enriched: true, provider: enriched.provider, applied_fields: appliedFields });
     });
     server.registerTool('subscriber_export', {
+        title: 'Subscriber Export',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Export a contact data portability bundle with contact metadata, email history, and suppression status.',
         inputSchema: {
             contactId: z.string().uuid(),
@@ -1022,6 +1267,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j(result);
     });
     server.registerTool('set_subscriber_tags', {
+        title: 'Set Subscriber Tags',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Add or remove tags from one or more contacts',
         inputSchema: {
             contact_ids: z.array(z.string().uuid()).min(1),
@@ -1036,7 +1288,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         for (const cid of contact_ids) {
             const { data: contact } = await db()
                 .from('subscribers')
-                .select('tags')
+                .select('id, email, first_name, last_name, custom_properties, tags')
                 .eq('id', cid)
                 .eq('project_id', projectId)
                 .maybeSingle();
@@ -1054,12 +1306,21 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .update({ tags: merged })
                 .eq('id', cid)
                 .eq('project_id', projectId);
-            if (!error)
+            if (!error) {
                 updated++;
+                await writeBackMcpContact(projectId, contact, { tags: merged });
+            }
         }
         return j({ updated, total: contact_ids.length, add_tags, remove_tags });
     });
     server.registerTool('estimate_segment_size', {
+        title: 'Estimate Segment Size',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Estimate how many contacts match filter criteria, with a sample. Useful before creating a segment.',
         inputSchema: {
             lifecycle_stage: z.enum(['new', 'active', 'cooling', 'cold', 'churned', 'lead', 'trial', 'customer', 'win-back']).optional(),
@@ -1174,17 +1435,26 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j({ total: count ?? (data ?? []).length, sample: data ?? [] });
     });
     server.registerTool('identify_inactive', {
+        title: 'Identify Inactive',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Find contacts with no engagement in N days. Dry run by default; set dry_run=false to suppress them.',
         inputSchema: {
             days: z.number().int().min(1).optional().default(90).describe('Inactivity threshold in days'),
             site_id: z.string().uuid().optional(),
             dry_run: z.boolean().optional().default(true).describe('Preview only (true) or suppress (false)'),
             limit: z.number().int().min(1).max(200).optional().default(20),
+            approval_id: z.string().uuid().optional().describe('Required when dry_run=false. Get this by calling once without it, then have a human approve via dashboard.'),
         },
-    }, async ({ days = 90, site_id, dry_run = true, limit = 20 }) => {
+    }, async ({ days = 90, site_id, dry_run = true, limit = 20, approval_id }) => {
         const projectId = getProjectId();
         const sampleLimit = Math.min(limit, 200);
         const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        const approvalParams = { days, site_id, dry_run: false, limit: sampleLimit };
         let q = db()
             .from('subscribers')
             .select('id, email, first_name, last_name, engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_emails_sent')
@@ -1213,6 +1483,24 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             return txt(`Error: ${error.message}`);
         const inactive = (contacts ?? []).filter((c) => !suppressedSet.has(c.email));
         if (!dry_run && inactive.length > 0) {
+            const channelContext = currentChannelContext();
+            const decision = assertChannelCanExecute('identify_inactive', approvalParams, channelContext);
+            if (!decision.allowed)
+                return txt(decision.reason ?? 'This channel cannot request this action.');
+            if (decision.tier !== 'autonomous') {
+                if (!approval_id) {
+                    const approval = await requestApproval('identify_inactive', approvalParams, undefined, channelContext);
+                    return j({
+                        ...approval,
+                        preview: { inactive_count: inactive.length, sample: inactive },
+                        message: `Will suppress ${inactive.length} contact(s) inactive for ${days} days. Requires human approval.`,
+                    });
+                }
+                const check = await checkApproval(approval_id, { consume: true, action: 'identify_inactive', params: approvalParams });
+                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 suppressionRows = inactive.map((c) => ({
                 project_id: projectId,
                 email: c.email,
@@ -1239,6 +1527,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         });
     });
     server.registerTool('remove_suppression', {
+        title: 'Remove Suppression',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Remove an email address from the suppression list',
         inputSchema: {
             email: z.string().email(),
@@ -1258,6 +1553,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j({ removed: true, email, previous_reason: data.reason });
     });
     server.registerTool('find_duplicates', {
+        title: 'Find Duplicates',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Find duplicate contacts using fuzzy email matching and exact name matching. Returns grouped candidates with confidence scores.',
         inputSchema: {
             confidence_threshold: z.number().min(0.5).max(1).optional().describe('Minimum similarity (0.5-1.0, default 0.8)'),
@@ -1368,6 +1670,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j({ duplicate_groups: result, total_groups: result.length });
     });
     server.registerTool('merge_subscribers', {
+        title: 'Merge Subscribers',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Merge duplicate contacts into a target. Consolidates subscriptions, enrollments, email history, and consent records. Source contacts are deleted. Requires human approval via dashboard.',
         inputSchema: {
             target_id: z.string().uuid().describe('Contact to keep'),
@@ -1387,18 +1696,23 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .select('id, email, first_name, last_name')
             .in('id', source_ids)
             .eq('project_id', getProjectId());
+        const approvalParams = {
+            target_id, target_email: target?.email,
+            source_ids, source_count: (sources ?? []).length,
+        };
         if (!approval_id) {
-            const approval = await requestApproval('merge_subscribers', {
-                target_id, target_email: target?.email,
-                source_ids, source_count: (sources ?? []).length,
-            });
+            const channelContext = currentChannelContext();
+            const decision = assertChannelCanExecute('merge_subscribers', { target_id, source_ids }, channelContext);
+            if (!decision.allowed)
+                return txt(decision.reason ?? 'This channel cannot request this action.');
+            const approval = await requestApproval('merge_subscribers', approvalParams, undefined, channelContext);
             return j({
                 ...approval,
                 preview: { target, sources: sources ?? [] },
                 message: `Will merge ${(sources ?? []).length} contact(s) into ${target?.email ?? target_id}. Source contacts will be deleted. Requires human approval.`,
             });
         }
-        const check = await checkApproval(approval_id, { consume: true });
+        const check = await checkApproval(approval_id, { consume: true, action: 'merge_subscribers', params: approvalParams });
         if (!check.approved) {
             return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
         }
@@ -1413,6 +1727,13 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         return j(data);
     });
     server.registerTool('get_contact_schema', {
+        title: 'Get Contact Schema',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Discover all custom_properties keys used across contacts for a site. Returns the list of keys, example values, and merge tag syntax so you can use them in campaigns. Call this before generating emails to know what personalisation data is available.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site to inspect — only contacts belonging to this site are sampled'),