@agifyai/leadify-mcp 1.4.1

package/dist/tools/personas.js

@@ -0,0 +1,1268 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { LeadifyApiError, toolResult, toolError, handleToolError } from "../types.js";
+// ─── Shared sub-schemas ────────────────────────────────────────────────────
+// hotCriteria / warmCriteria / coldCriteria / disqualifiedCriteria
+// Accept either a free-form string OR a structured {criteria, examples, weight} object.
+const criteriaTier = z.union([
+    z.string(),
+    z
+        .object({
+        criteria: z.string().optional(),
+        examples: z.string().optional(),
+        weight: z.number().optional(),
+    })
+        .passthrough(),
+]);
+const lookalikeClient = z.object({
+    name: z.string().describe("Client/company name (required)."),
+    sector: z.string().optional(),
+    size: z.string().optional(),
+    segment: z.string().optional(),
+    comparison_criteria: z
+        .string()
+        .optional()
+        .describe("Why this client is a useful reference."),
+});
+const painPoint = z.object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+});
+const cardAnalysisSection = z.object({
+    id: z.string().optional(),
+    labels: z
+        .record(z.string())
+        .optional()
+        .describe("Multilingual labels, keyed by language code (e.g. { fr, en })."),
+    instructions: z.string().optional(),
+});
+const signalTierRule = z.object({
+    signal_id: z.string().optional(),
+    tier: z.enum(["hot", "warm", "cold"]).optional(),
+});
+const outreachTemplate = z
+    .object({
+    id: z.string().optional(),
+    channel: z.string().optional(),
+    signal: z
+        .string()
+        .optional()
+        .describe("Must exist in outreach_signal_routing.signals."),
+    field_name: z.string().optional(),
+    signal_context: z.string().optional(),
+    purpose: z.string().optional(),
+    example: z.string().optional(),
+    max_length: z.number().optional(),
+    label: z.string().optional(),
+    subject: z.string().optional(),
+    body: z.string().optional(),
+})
+    .passthrough();
+const outreachField = z
+    .object({
+    key: z.string().optional(),
+    label: z.string().optional(),
+    source: z.string().optional(),
+})
+    .passthrough();
+const extraPromptPhase = z.object({
+    scope: z.enum(["qualify", "outreach"]).optional(),
+    insertion_point: z
+        .enum(["prefix", "phase_1_5", "phase_2_extra", "suffix"])
+        .describe("Where in the prompt to inject this snippet."),
+    content: z.string().describe("Snippet content."),
+});
+const senderOverride = z.object({
+    name: z.string().describe("Sender display name (required)."),
+    title: z.string().optional(),
+});
+// ICP strategy — mental map consumed verbatim by the outreach agent preflight.
+const icpStrategyShape = {
+    dealType: z.string().optional(),
+    dreamOutcome: z.string().optional(),
+    mainPains: z.array(z.string()).optional(),
+    keyObjections: z.array(z.string()).optional(),
+    decisionDrivers: z.array(z.string()).optional(),
+};
+// camelCase mapping for nested objects that the backend expects as-is.
+function mapLookalikeClient(c) {
+    const out = { name: c.name };
+    if (c.sector !== undefined)
+        out.sector = c.sector;
+    if (c.size !== undefined)
+        out.size = c.size;
+    if (c.segment !== undefined)
+        out.segment = c.segment;
+    if (c.comparison_criteria !== undefined)
+        out.comparisonCriteria = c.comparison_criteria;
+    return out;
+}
+function mapCardSection(s) {
+    const out = {};
+    if (s.id !== undefined)
+        out.id = s.id;
+    if (s.labels !== undefined)
+        out.labels = s.labels;
+    if (s.instructions !== undefined)
+        out.instructions = s.instructions;
+    return out;
+}
+function mapOutreachTemplate(t) {
+    const out = {};
+    if (t.id !== undefined)
+        out.id = t.id;
+    if (t.channel !== undefined)
+        out.channel = t.channel;
+    if (t.signal !== undefined)
+        out.signal = t.signal;
+    if (t.field_name !== undefined)
+        out.fieldName = t.field_name;
+    if (t.signal_context !== undefined)
+        out.signalContext = t.signal_context;
+    if (t.purpose !== undefined)
+        out.purpose = t.purpose;
+    if (t.example !== undefined)
+        out.example = t.example;
+    if (t.max_length !== undefined)
+        out.maxLength = t.max_length;
+    if (t.label !== undefined)
+        out.label = t.label;
+    if (t.subject !== undefined)
+        out.subject = t.subject;
+    if (t.body !== undefined)
+        out.body = t.body;
+    return out;
+}
+function mapSignalTierRule(r) {
+    const out = {};
+    if (r.signal_id !== undefined)
+        out.signalId = r.signal_id;
+    if (r.tier !== undefined)
+        out.tier = r.tier;
+    return out;
+}
+function mapExtraPromptPhase(p) {
+    const out = {
+        insertionPoint: p.insertion_point,
+        content: p.content,
+    };
+    if (p.scope !== undefined)
+        out.scope = p.scope;
+    return out;
+}
+/**
+ * Tag a thrown error with which RMW step failed (read vs write) and surface
+ * the inner status / response body. Patch tools have a 2-step flow (GET-then-
+ * POST) and a bare "Persona not found" gives no clue which call broke.
+ */
+class PersonaPatchError extends Error {
+    step;
+    path;
+    statusCode;
+    responseBody;
+    hint;
+    constructor(step, path, statusCode, responseBody, hint) {
+        const inner = typeof responseBody === "object" &&
+            responseBody !== null &&
+            "error" in responseBody
+            ? String(responseBody.error)
+            : statusCode != null
+                ? `HTTP ${statusCode}`
+                : "request failed";
+        super(`[step: ${step}] ${path} → ${inner}${hint ? ` — ${hint}` : ""}`);
+        this.step = step;
+        this.path = path;
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+        this.hint = hint;
+        this.name = "PersonaPatchError";
+    }
+}
+/**
+ * Read a persona for the RMW patch flow.
+ *
+ * Backend asymmetry (verified empirically + documented in
+ * `agentic/trigger_agify` LeadifyCrmClient comments):
+ *   - GET /api/persona/{id}      → strict `persona.organizationId === user.organizationId`
+ *   - POST /api/persona (upsert) → permissive `canAccessOrg(user, ...)`
+ *   - GET /api/persona  (list)   → permissive via `buildOrgFilter`
+ *
+ * For super-admin keys or cross-org access, GET-by-id 404s while POST-upsert
+ * succeeds. Without a fallback, every patch tool 404s in those cases even
+ * when the user can clearly write to the persona via upsert.
+ *
+ * Strategy: fast-path the direct GET; on 404, fall back to the permissive
+ * list endpoint and find by id. Other errors propagate immediately.
+ */
+async function fetchPersona(id) {
+    const directPath = `/api/persona/${encodeURIComponent(id)}`;
+    try {
+        const data = await getClient().get(directPath);
+        if (!data || typeof data !== "object") {
+            throw new PersonaPatchError("read", directPath, null, data, "Unexpected response shape (expected an object).");
+        }
+        // GET-by-id returns the persona body directly; defensive about a future
+        // projected/wrapped shape.
+        const persona = data.persona;
+        return persona ?? data;
+    }
+    catch (err) {
+        if (!(err instanceof LeadifyApiError) || err.statusCode !== 404) {
+            throw err;
+        }
+        // 404 on direct GET — fall through to list-based lookup.
+    }
+    // Permissive fallback: list returns everything the API key can see
+    // (own org + globals for regular users; cross-org for super admins).
+    const listPath = "/api/persona";
+    let listed;
+    try {
+        listed = await getClient().get(listPath);
+    }
+    catch (err) {
+        if (err instanceof LeadifyApiError) {
+            throw new PersonaPatchError("lookup", listPath, err.statusCode, err.responseBody, "Direct GET 404'd; fallback list lookup also failed.");
+        }
+        throw err;
+    }
+    const personas = listed?.personas;
+    if (!Array.isArray(personas)) {
+        throw new PersonaPatchError("lookup", listPath, null, listed, "List response missing 'personas' array.");
+    }
+    const found = personas.find((p) => p.id === id);
+    if (!found) {
+        throw new PersonaPatchError("lookup", directPath, 404, { error: "Persona not found" }, `Persona id "${id}" is not in your accessible personas. Verify the id with list_personas. ` +
+            `Note: GET /api/persona/{id} uses strict org-equality and 404s for cross-org access — ` +
+            `super-admin keys may need to operate via lead-group context. If list_personas returns this ` +
+            `id, the backend GET handler is the bug; tracker: align it with upsert's canAccessOrg semantics.`);
+    }
+    return found;
+}
+async function postPersonaUpdate(id, name, fieldsToWrite) {
+    const path = "/api/persona";
+    try {
+        return await getClient().post(path, {
+            id,
+            name,
+            ...fieldsToWrite,
+        });
+    }
+    catch (err) {
+        if (err instanceof LeadifyApiError) {
+            throw new PersonaPatchError("write", path, err.statusCode, err.responseBody, `Fields written: ${Object.keys(fieldsToWrite).join(", ") || "(none beyond id+name)"}`);
+        }
+        throw err;
+    }
+}
+function asObject(v) {
+    return v && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : {};
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+/**
+ * Error handler for persona tools. Serializes PersonaPatchError into
+ * structured details (step, path, statusCode, responseBody, hint) so the
+ * caller can see exactly which sub-call failed and why — useful for the
+ * 12 patch tools' read-then-write flow. For other errors (LeadifyApiError
+ * from the wholesale tools, plain Error), falls through to handleToolError.
+ */
+function handlePersonaToolError(error) {
+    if (error instanceof PersonaPatchError) {
+        return toolError(error.message, {
+            step: error.step,
+            path: error.path,
+            statusCode: error.statusCode,
+            response: error.responseBody,
+            hint: error.hint,
+        });
+    }
+    return handleToolError(error);
+}
+// ─── Tool registrations ────────────────────────────────────────────────────
+export function registerPersonaTools(server) {
+    // ════════════════════════════════════════════════════════════════════════
+    // ESCAPE HATCH — wholesale upsert
+    // ════════════════════════════════════════════════════════════════════════
+    // ── upsert_persona ─────────────────────────────────────────────────────
+    server.tool("upsert_persona", "WHOLESALE create-or-update for a persona. Use to CREATE (no id) or to fully " +
+        "rewrite a persona. For partial edits, ALWAYS prefer the granular " +
+        "update_persona_* tools — they do safe read-modify-write merges and avoid " +
+        "wiping JSON columns you didn't intend to touch (each JSON column passed in " +
+        "this tool is replaced wholesale, so omitted sub-keys are LOST).", {
+        // core
+        id: z
+            .string()
+            .optional()
+            .describe("Persona ID to update an existing persona. Omit to create a new one."),
+        name: z.string().describe("Persona name (required)."),
+        organization_id: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Target organization ID (Clerk org ID). Absent = caller's org. Pass null to make the persona global (admin only)."),
+        description: z.string().optional().describe("Detailed persona description."),
+        // targeting
+        target_profile: z
+            .record(z.unknown())
+            .optional()
+            .describe("Target criteria. Common keys: job_titles, specialties, seniority_min, decision_maker, " +
+            "buying_power, target_company_types, min_company_size, interest_topics."),
+        disqualification_criteria: z
+            .record(z.unknown())
+            .optional()
+            .describe("Exclusion rules. Common keys: reasons (array of strings)."),
+        messaging_guidelines: z
+            .record(z.unknown())
+            .optional()
+            .describe("Message approach. Common keys: tone, language, can_mention, must_not_mention, value_propositions."),
+        active_tools: z
+            .array(z.string())
+            .optional()
+            .describe("Active monitoring/sourcing tools for this persona."),
+        // scoring tiers
+        hot_criteria: criteriaTier
+            .optional()
+            .describe("Criteria that make a lead 'hot'. Either a free-form string or {criteria, examples, weight}."),
+        warm_criteria: criteriaTier.optional().describe("Criteria that make a lead 'warm'."),
+        cold_criteria: criteriaTier.optional().describe("Criteria that make a lead 'cold'."),
+        disqualified_criteria: criteriaTier
+            .optional()
+            .describe("Criteria that disqualify a lead entirely."),
+        // references + pains
+        lookalike_clients: z
+            .array(lookalikeClient)
+            .optional()
+            .describe("2–3 official lookalike clients. Each must have at least a name."),
+        pain_points: z
+            .array(painPoint)
+            .optional()
+            .describe("Structured business pain points ({title, description})."),
+        // ICP strategy — mental map consumed verbatim by the outreach agent preflight
+        icp_strategy: z
+            .object(icpStrategyShape)
+            .passthrough()
+            .optional()
+            .describe("ICP strategy. Mental map for the outreach agent: {dealType, dreamOutcome, mainPains[], keyObjections[], decisionDrivers[]}."),
+        // behaviour flags
+        strict_match: z
+            .boolean()
+            .optional()
+            .describe("If true, reject non-perfectly-aligned leads."),
+        agent_domain: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Agent identity string (e.g. 'for medtech companies')."),
+        workflow_mode: z
+            .enum(["company_first", "person_first"])
+            .nullable()
+            .optional()
+            .describe("Qualification mode."),
+        output_language: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("AI output language code (fr, en, de, …)."),
+        enable_signals: z
+            .boolean()
+            .optional()
+            .describe("Enable business signal detection for this persona."),
+        // prompt engineering
+        normalization_rules: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Free-form markdown injected into the ICP prompt."),
+        decision_maker_keywords: z
+            .record(z.array(z.string()))
+            .optional()
+            .describe("Terms implying decision power, keyed by language code. Example: { fr: ['Directeur', 'Chef de pôle'] }."),
+        card_analysis_sections: z
+            .object({
+            required: z.array(cardAnalysisSection).optional(),
+            optional: z.array(cardAnalysisSection).optional(),
+        })
+            .optional()
+            .describe("Analysis blocks separated into 'required' and 'optional'."),
+        signal_guidance: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Free-form markdown injected verbatim into signal prompt."),
+        signal_tier_rules: z
+            .object({
+            rules: z.array(signalTierRule).optional(),
+        })
+            .optional()
+            .describe("Rules mapping signal → tier (hot/warm/cold)."),
+        // outreach
+        outreach_signal_routing: z
+            .object({
+            signal_source_field: z
+                .string()
+                .optional()
+                .describe("Card field to read (e.g. card_signals)."),
+            default_signal: z
+                .string()
+                .optional()
+                .describe("Must exist in 'signals' array."),
+            signals: z
+                .array(z.string())
+                .optional()
+                .describe("Exhaustive list of recognized signals."),
+        })
+            .optional()
+            .describe("Extract signal source from card lead + default signal. All three sub-fields are optional."),
+        outreach_templates: z
+            .array(outreachTemplate)
+            .optional()
+            .describe("Outreach templates by channel. Each template: {id, channel, signal, field_name, signal_context, purpose, example, max_length, label, subject, body}."),
+        outreach_fields: z
+            .array(outreachField)
+            .optional()
+            .describe("Variables referenceable in templates. Each: {key, label, source}."),
+        tone_instructions: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Free-form markdown for voice / tone guidance."),
+        context: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Free-form markdown appended to the ICP prompt."),
+        extra_prompt_phases: z
+            .array(extraPromptPhase)
+            .optional()
+            .describe("Snippets inserted at named points. scope: 'qualify' | 'outreach'; insertion_point: 'prefix' | 'phase_1_5' | 'phase_2_extra' | 'suffix'."),
+        // sender
+        sender_override: senderOverride
+            .nullable()
+            .optional()
+            .describe("Override SDR identity at persona level ({name, title})."),
+    }, async (params) => {
+        try {
+            const body = { name: params.name };
+            if (params.id !== undefined)
+                body.id = params.id;
+            if (params.organization_id !== undefined)
+                body.organizationId = params.organization_id;
+            if (params.description !== undefined)
+                body.description = params.description;
+            if (params.target_profile !== undefined)
+                body.targetProfile = params.target_profile;
+            if (params.disqualification_criteria !== undefined)
+                body.disqualificationCriteria = params.disqualification_criteria;
+            if (params.messaging_guidelines !== undefined)
+                body.messagingGuidelines = params.messaging_guidelines;
+            if (params.active_tools !== undefined)
+                body.activeTools = params.active_tools;
+            if (params.hot_criteria !== undefined)
+                body.hotCriteria = params.hot_criteria;
+            if (params.warm_criteria !== undefined)
+                body.warmCriteria = params.warm_criteria;
+            if (params.cold_criteria !== undefined)
+                body.coldCriteria = params.cold_criteria;
+            if (params.disqualified_criteria !== undefined)
+                body.disqualifiedCriteria = params.disqualified_criteria;
+            if (params.lookalike_clients !== undefined)
+                body.lookalikeClients = params.lookalike_clients.map(mapLookalikeClient);
+            if (params.pain_points !== undefined)
+                body.painPoints = params.pain_points;
+            if (params.icp_strategy !== undefined)
+                body.icpStrategy = params.icp_strategy;
+            if (params.strict_match !== undefined)
+                body.strictMatch = params.strict_match;
+            if (params.agent_domain !== undefined)
+                body.agentDomain = params.agent_domain;
+            if (params.workflow_mode !== undefined)
+                body.workflowMode = params.workflow_mode;
+            if (params.output_language !== undefined)
+                body.outputLanguage = params.output_language;
+            if (params.enable_signals !== undefined)
+                body.enableSignals = params.enable_signals;
+            if (params.normalization_rules !== undefined)
+                body.normalizationRules = params.normalization_rules;
+            if (params.decision_maker_keywords !== undefined)
+                body.decisionMakerKeywords = params.decision_maker_keywords;
+            if (params.card_analysis_sections !== undefined) {
+                const cas = {};
+                if (params.card_analysis_sections.required !== undefined)
+                    cas.required = params.card_analysis_sections.required.map(mapCardSection);
+                if (params.card_analysis_sections.optional !== undefined)
+                    cas.optional = params.card_analysis_sections.optional.map(mapCardSection);
+                body.cardAnalysisSections = cas;
+            }
+            if (params.signal_guidance !== undefined)
+                body.signalGuidance = params.signal_guidance;
+            if (params.signal_tier_rules !== undefined) {
+                body.signalTierRules = {
+                    rules: (params.signal_tier_rules.rules ?? []).map(mapSignalTierRule),
+                };
+            }
+            if (params.outreach_signal_routing !== undefined) {
+                const osr = {};
+                if (params.outreach_signal_routing.signal_source_field !== undefined)
+                    osr.signalSourceField =
+                        params.outreach_signal_routing.signal_source_field;
+                if (params.outreach_signal_routing.default_signal !== undefined)
+                    osr.defaultSignal = params.outreach_signal_routing.default_signal;
+                if (params.outreach_signal_routing.signals !== undefined)
+                    osr.signals = params.outreach_signal_routing.signals;
+                body.outreachSignalRouting = osr;
+            }
+            if (params.outreach_templates !== undefined)
+                body.outreachTemplates = params.outreach_templates.map(mapOutreachTemplate);
+            if (params.outreach_fields !== undefined)
+                body.outreachFields = params.outreach_fields;
+            if (params.tone_instructions !== undefined)
+                body.toneInstructions = params.tone_instructions;
+            if (params.context !== undefined)
+                body.context = params.context;
+            if (params.extra_prompt_phases !== undefined)
+                body.extraPromptPhases =
+                    params.extra_prompt_phases.map(mapExtraPromptPhase);
+            if (params.sender_override !== undefined)
+                body.senderOverride = params.sender_override;
+            const data = await getClient().post("/api/persona", body);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── get_persona ────────────────────────────────────────────────────────
+    server.tool("get_persona", "Retrieve a single persona by ID, including all lead groups it's assigned to.", {
+        id: z.string().describe("Persona ID."),
+    }, async ({ id }) => {
+        try {
+            const data = await getClient().get(`/api/persona/${encodeURIComponent(id)}`);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── list_personas ──────────────────────────────────────────────────────
+    server.tool("list_personas", "List all personas accessible to the caller, optionally scoped to a specific organization " +
+        "and/or including global personas. Use this to discover persona IDs before calling " +
+        "get_persona, upsert_persona (for updates), or assigning a persona to a lead group. " +
+        "Returns a COMPACT view by default (id, name, organizationId, truncated description) " +
+        "to avoid blowing up context — full persona objects can be heavy (~10k chars each). " +
+        "Pass verbose=true to get the full objects, or call get_persona(id) for a single full persona.", {
+        organization_id: z
+            .string()
+            .optional()
+            .describe("Filter by organization ID. Pass the literal string 'null' to list only global personas."),
+        include_globals: z
+            .boolean()
+            .optional()
+            .describe("If true (default), include global personas (organizationId === null) alongside org-scoped ones."),
+        verbose: z
+            .boolean()
+            .optional()
+            .describe("If true, return full persona objects with every field. Defaults to false (compact view: id, name, organizationId, short description)."),
+    }, async ({ organization_id, include_globals, verbose }) => {
+        try {
+            const params = new URLSearchParams();
+            if (organization_id !== undefined)
+                params.set("organizationId", organization_id);
+            if (include_globals !== undefined)
+                params.set("includeGlobals", String(include_globals));
+            const data = await getClient().get("/api/persona", params);
+            if (verbose)
+                return toolResult(data);
+            // Project to compact view: id, name, organizationId, truncated description.
+            const personas = data && typeof data === "object" && "personas" in data
+                ? data.personas
+                : null;
+            if (!Array.isArray(personas))
+                return toolResult(data); // unexpected shape → fall through
+            const DESC_MAX = 200;
+            const compact = personas.map((p) => {
+                const obj = p;
+                const desc = typeof obj.description === "string" ? obj.description : undefined;
+                return {
+                    id: obj.id,
+                    name: obj.name,
+                    organizationId: obj.organizationId ?? null,
+                    ...(desc !== undefined && {
+                        description: desc.length > DESC_MAX ? `${desc.slice(0, DESC_MAX)}…` : desc,
+                    }),
+                };
+            });
+            return toolResult({
+                personas: compact,
+                count: compact.length,
+                _note: "Compact view. Call get_persona(id) for full details, or list_personas with verbose=true.",
+            });
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── delete_persona ─────────────────────────────────────────────────────
+    server.tool("delete_persona", "Permanently delete a persona by ID. Irreversible. Fails if the persona is still assigned " +
+        "to any lead group or referenced by an active campaign. Always confirm with the user " +
+        "before calling this tool.", {
+        id: z.string().describe("Persona ID to delete."),
+    }, async ({ id }) => {
+        try {
+            const data = await getClient().delete(`/api/persona/${encodeURIComponent(id)}`);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── move_persona ───────────────────────────────────────────────────────
+    server.tool("move_persona", "Move a persona to a different organization (or make it global by passing null). " +
+        "Admin permission required. Useful when promoting an org-scoped persona to a shared " +
+        "global template, or reassigning between orgs.", {
+        id: z.string().describe("Persona ID to move."),
+        organization_id: z
+            .string()
+            .nullable()
+            .describe("Target organization ID (Clerk org ID). Pass null to make the persona global."),
+    }, async ({ id, organization_id }) => {
+        try {
+            const data = await getClient().post(`/api/persona/${encodeURIComponent(id)}/move`, { organizationId: organization_id });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ════════════════════════════════════════════════════════════════════════
+    // GRANULAR PATCH TOOLS — read-modify-write, scoped to one section each
+    // ════════════════════════════════════════════════════════════════════════
+    // ── update_persona_identity ────────────────────────────────────────────
+    server.tool("update_persona_identity", "Patch top-level scalar fields of a persona (name, description, agent_domain, " +
+        "output_language, workflow_mode, strict_match, enable_signals, sender_override). " +
+        "Pass only the fields you want to change. Other persona sections are untouched.", {
+        id: z.string().describe("Persona ID."),
+        name: z.string().min(1).optional().describe("New persona name."),
+        description: z.string().nullable().optional().describe("Detailed description."),
+        agent_domain: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Agent identity string (e.g. 'for medtech companies')."),
+        output_language: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Output language code (fr, en, de, …)."),
+        workflow_mode: z
+            .enum(["company_first", "person_first"])
+            .nullable()
+            .optional()
+            .describe("Qualification mode."),
+        strict_match: z
+            .boolean()
+            .optional()
+            .describe("If true, reject non-perfectly-aligned leads."),
+        enable_signals: z
+            .boolean()
+            .optional()
+            .describe("Enable business signal detection for this persona."),
+        sender_override: senderOverride
+            .nullable()
+            .optional()
+            .describe("Override SDR identity at persona level ({name, title}). Pass null to clear."),
+    }, async ({ id, name, description, agent_domain, output_language, workflow_mode, strict_match, enable_signals, sender_override, }) => {
+        try {
+            if (name === undefined &&
+                description === undefined &&
+                agent_domain === undefined &&
+                output_language === undefined &&
+                workflow_mode === undefined &&
+                strict_match === undefined &&
+                enable_signals === undefined &&
+                sender_override === undefined) {
+                return toolError("Provide at least one field to update.");
+            }
+            const current = await fetchPersona(id);
+            const body = {};
+            if (description !== undefined)
+                body.description = description;
+            if (agent_domain !== undefined)
+                body.agentDomain = agent_domain;
+            if (output_language !== undefined)
+                body.outputLanguage = output_language;
+            if (workflow_mode !== undefined)
+                body.workflowMode = workflow_mode;
+            if (strict_match !== undefined)
+                body.strictMatch = strict_match;
+            if (enable_signals !== undefined)
+                body.enableSignals = enable_signals;
+            if (sender_override !== undefined)
+                body.senderOverride = sender_override;
+            const data = await postPersonaUpdate(id, name ?? current.name, body);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_target_profile ──────────────────────────────────────
+    server.tool("update_persona_target_profile", "Patch the targetProfile JSON column. Reads current targetProfile, shallow-merges " +
+        "the keys you pass, optionally removes specified keys, then writes back. Common " +
+        "keys: job_titles, specialties, seniority_min, decision_maker, buying_power, " +
+        "target_company_types, min_company_size, interest_topics. Other targetProfile " +
+        "keys remain intact.", {
+        id: z.string().describe("Persona ID."),
+        patch: z
+            .record(z.unknown())
+            .optional()
+            .describe("Object whose keys are merged into the existing targetProfile (shallow). Keys you don't pass remain intact."),
+        remove_keys: z
+            .array(z.string())
+            .optional()
+            .describe("Keys to delete from targetProfile."),
+    }, async ({ id, patch, remove_keys }) => {
+        try {
+            if ((patch === undefined || Object.keys(patch).length === 0) &&
+                (remove_keys === undefined || remove_keys.length === 0)) {
+                return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
+            }
+            const current = await fetchPersona(id);
+            const next = { ...asObject(current.targetProfile), ...(patch ?? {}) };
+            for (const k of remove_keys ?? [])
+                delete next[k];
+            const data = await postPersonaUpdate(id, current.name, { targetProfile: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_disqualification ────────────────────────────────────
+    server.tool("update_persona_disqualification", "Patch the disqualificationCriteria JSON column (shallow merge). Common key: " +
+        "reasons (array of strings). Other keys remain intact.", {
+        id: z.string().describe("Persona ID."),
+        patch: z
+            .record(z.unknown())
+            .optional()
+            .describe("Object whose keys are merged into existing disqualificationCriteria (shallow)."),
+        remove_keys: z
+            .array(z.string())
+            .optional()
+            .describe("Keys to delete from disqualificationCriteria."),
+    }, async ({ id, patch, remove_keys }) => {
+        try {
+            if ((patch === undefined || Object.keys(patch).length === 0) &&
+                (remove_keys === undefined || remove_keys.length === 0)) {
+                return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
+            }
+            const current = await fetchPersona(id);
+            const next = { ...asObject(current.disqualificationCriteria), ...(patch ?? {}) };
+            for (const k of remove_keys ?? [])
+                delete next[k];
+            const data = await postPersonaUpdate(id, current.name, { disqualificationCriteria: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_messaging ───────────────────────────────────────────
+    server.tool("update_persona_messaging", "Patch the messagingGuidelines JSON column (shallow merge). Common keys: tone, " +
+        "language, can_mention, must_not_mention, value_propositions. Other keys remain intact.", {
+        id: z.string().describe("Persona ID."),
+        patch: z
+            .record(z.unknown())
+            .optional()
+            .describe("Object whose keys are merged into existing messagingGuidelines (shallow)."),
+        remove_keys: z
+            .array(z.string())
+            .optional()
+            .describe("Keys to delete from messagingGuidelines."),
+    }, async ({ id, patch, remove_keys }) => {
+        try {
+            if ((patch === undefined || Object.keys(patch).length === 0) &&
+                (remove_keys === undefined || remove_keys.length === 0)) {
+                return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
+            }
+            const current = await fetchPersona(id);
+            const next = { ...asObject(current.messagingGuidelines), ...(patch ?? {}) };
+            for (const k of remove_keys ?? [])
+                delete next[k];
+            const data = await postPersonaUpdate(id, current.name, { messagingGuidelines: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_active_tools ────────────────────────────────────────
+    server.tool("update_persona_active_tools", "Replace the activeTools list wholesale, OR add/remove specific entries while " +
+        "preserving the rest. Use 'tools' to fully replace; use 'add' / 'remove' for " +
+        "incremental edits (deduped).", {
+        id: z.string().describe("Persona ID."),
+        tools: z
+            .array(z.string())
+            .optional()
+            .describe("Full replacement list. Mutually exclusive with add/remove."),
+        add: z
+            .array(z.string())
+            .optional()
+            .describe("Tools to add (no-op if already present)."),
+        remove: z
+            .array(z.string())
+            .optional()
+            .describe("Tools to remove (no-op if absent)."),
+    }, async ({ id, tools, add, remove }) => {
+        try {
+            if (tools === undefined && add === undefined && remove === undefined) {
+                return toolError("Provide one of: tools, add, remove.");
+            }
+            if (tools !== undefined && (add !== undefined || remove !== undefined)) {
+                return toolError("'tools' is mutually exclusive with 'add' / 'remove'.");
+            }
+            const current = await fetchPersona(id);
+            let next;
+            if (tools !== undefined) {
+                next = tools;
+            }
+            else {
+                const set = new Set(asArray(current.activeTools));
+                for (const t of add ?? [])
+                    set.add(t);
+                for (const t of remove ?? [])
+                    set.delete(t);
+                next = Array.from(set);
+            }
+            const data = await postPersonaUpdate(id, current.name, { activeTools: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_tier_criteria ───────────────────────────────────────
+    server.tool("update_persona_tier_criteria", "Patch a single qualification tier (hot, warm, cold, or disqualified) without " +
+        "touching the other three. Each tier accepts either a free-form string or " +
+        "{criteria, examples, weight}. When passing a structured patch, sub-fields are " +
+        "merged into the existing structured tier (if any) — pass only what you want " +
+        "to change. Passing a string REPLACES the tier entirely.", {
+        id: z.string().describe("Persona ID."),
+        tier: z
+            .enum(["hot", "warm", "cold", "disqualified"])
+            .describe("Which tier to patch."),
+        criteria: z
+            .union([
+            z.string(),
+            z
+                .object({
+                criteria: z.string().optional(),
+                examples: z.string().optional(),
+                weight: z.number().optional(),
+            })
+                .passthrough(),
+        ])
+            .describe("New tier value. String replaces wholesale; object is merged."),
+    }, async ({ id, tier, criteria }) => {
+        try {
+            const fieldMap = {
+                hot: "hotCriteria",
+                warm: "warmCriteria",
+                cold: "coldCriteria",
+                disqualified: "disqualifiedCriteria",
+            };
+            const field = fieldMap[tier];
+            const current = await fetchPersona(id);
+            let nextValue;
+            if (typeof criteria === "string") {
+                nextValue = criteria;
+            }
+            else {
+                const existing = current[field];
+                const base = existing && typeof existing === "object" && !Array.isArray(existing)
+                    ? existing
+                    : {};
+                nextValue = { ...base, ...criteria };
+            }
+            const data = await postPersonaUpdate(id, current.name, { [field]: nextValue });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_lookalike_client ────────────────────────────────────
+    server.tool("update_persona_lookalike_client", "Add, replace, or remove a single lookalike client without re-sending the whole " +
+        "list. Lookups are by client `name` (case-sensitive exact match). Reads the " +
+        "current lookalikeClients array, mutates the matched entry, writes the full " +
+        "list back. Use this instead of upsert_persona to avoid wiping the others.", {
+        id: z.string().describe("Persona ID."),
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append (fails if name already exists); replace = overwrite by name; remove = delete by name."),
+        name: z
+            .string()
+            .optional()
+            .describe("Lookup key for replace/remove. Required for those actions. For 'add', the name is taken from the client payload."),
+        client: lookalikeClient
+            .optional()
+            .describe("Client payload. Required for 'add' and 'replace'. Schema: {name, sector?, size?, segment?, comparison_criteria?}."),
+    }, async ({ id, action, name, client }) => {
+        try {
+            if ((action === "add" || action === "replace") && !client) {
+                return toolError(`client is required for action '${action}'.`);
+            }
+            if ((action === "replace" || action === "remove") && !name) {
+                return toolError(`name is required for action '${action}'.`);
+            }
+            const current = await fetchPersona(id);
+            const list = asArray(current.lookalikeClients).map((c) => ({ ...c }));
+            if (action === "add") {
+                const newName = client.name;
+                if (list.some((c) => c.name === newName)) {
+                    return toolError(`A lookalike client with name "${newName}" already exists. Use action 'replace' instead.`);
+                }
+                list.push(mapLookalikeClient(client));
+            }
+            else if (action === "replace") {
+                const idx = list.findIndex((c) => c.name === name);
+                if (idx === -1) {
+                    return toolError(`No lookalike client found with name "${name}".`);
+                }
+                list[idx] = mapLookalikeClient(client);
+            }
+            else {
+                const before = list.length;
+                const filtered = list.filter((c) => c.name !== name);
+                if (filtered.length === before) {
+                    return toolError(`No lookalike client found with name "${name}".`);
+                }
+                list.length = 0;
+                list.push(...filtered);
+            }
+            const data = await postPersonaUpdate(id, current.name, {
+                lookalikeClients: list,
+            });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_pain_point ──────────────────────────────────────────
+    server.tool("update_persona_pain_point", "Add, replace, or remove a single pain point without re-sending the whole list. " +
+        "Pain points have no stable id — entries are addressed by zero-based index. " +
+        "Beware: indices shift after a remove, so re-fetch before chaining edits.", {
+        id: z.string().describe("Persona ID."),
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append; replace = overwrite at index; remove = delete at index."),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Zero-based index. Required for 'replace' and 'remove'."),
+        pain: painPoint
+            .optional()
+            .describe("Pain payload {title?, description?}. Required for 'add' and 'replace'."),
+    }, async ({ id, action, index, pain }) => {
+        try {
+            if ((action === "add" || action === "replace") && !pain) {
+                return toolError(`pain is required for action '${action}'.`);
+            }
+            if ((action === "replace" || action === "remove") && index === undefined) {
+                return toolError(`index is required for action '${action}'.`);
+            }
+            const current = await fetchPersona(id);
+            const list = asArray(current.painPoints).map((p) => ({ ...p }));
+            if (action === "add") {
+                list.push(pain);
+            }
+            else if (action === "replace") {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
+                }
+                list[index] = pain;
+            }
+            else {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
+                }
+                list.splice(index, 1);
+            }
+            const data = await postPersonaUpdate(id, current.name, { painPoints: list });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_outreach_template ───────────────────────────────────
+    server.tool("update_persona_outreach_template", "Add, replace, or remove a single outreach template without re-sending the whole " +
+        "list. Lookups are by template `id` (recommended) or by composite key " +
+        "(channel + signal + field_name) when no id is set. WARNING: if the persona's " +
+        "outreachSignalRouting.signals[] is configured, every template's `signal` must " +
+        "be in that list — the API rejects with 422 otherwise.", {
+        id: z.string().describe("Persona ID."),
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append; replace = overwrite by id (or composite key); remove = delete by id (or composite key)."),
+        template_id: z
+            .string()
+            .optional()
+            .describe("Template id for replace/remove. Preferred lookup key."),
+        lookup_channel: z
+            .string()
+            .optional()
+            .describe("Fallback lookup: channel. Used together with lookup_signal + lookup_field_name when template_id is absent."),
+        lookup_signal: z
+            .string()
+            .optional()
+            .describe("Fallback lookup: signal."),
+        lookup_field_name: z
+            .string()
+            .optional()
+            .describe("Fallback lookup: field_name."),
+        template: outreachTemplate
+            .optional()
+            .describe("Template payload. Required for 'add' and 'replace'. Schema: {id, channel, signal, field_name, signal_context, purpose, example, max_length, label, subject, body}."),
+    }, async ({ id, action, template_id, lookup_channel, lookup_signal, lookup_field_name, template, }) => {
+        try {
+            if ((action === "add" || action === "replace") && !template) {
+                return toolError(`template is required for action '${action}'.`);
+            }
+            const matches = (t) => {
+                if (template_id)
+                    return t.id === template_id;
+                if (lookup_channel || lookup_signal || lookup_field_name) {
+                    return ((lookup_channel === undefined || t.channel === lookup_channel) &&
+                        (lookup_signal === undefined || t.signal === lookup_signal) &&
+                        (lookup_field_name === undefined || t.fieldName === lookup_field_name));
+                }
+                return false;
+            };
+            if (action !== "add" && !template_id && !lookup_channel && !lookup_signal && !lookup_field_name) {
+                return toolError("Provide template_id (preferred) or composite lookup (lookup_channel + lookup_signal + lookup_field_name).");
+            }
+            const current = await fetchPersona(id);
+            const list = asArray(current.outreachTemplates).map((t) => ({ ...t }));
+            if (action === "add") {
+                list.push(mapOutreachTemplate(template));
+            }
+            else if (action === "replace") {
+                const idx = list.findIndex(matches);
+                if (idx === -1) {
+                    return toolError("No matching template found for the given lookup.");
+                }
+                list[idx] = mapOutreachTemplate(template);
+            }
+            else {
+                const before = list.length;
+                const filtered = list.filter((t) => !matches(t));
+                if (filtered.length === before) {
+                    return toolError("No matching template found for the given lookup.");
+                }
+                list.length = 0;
+                list.push(...filtered);
+            }
+            const data = await postPersonaUpdate(id, current.name, {
+                outreachTemplates: list,
+            });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_outreach_signal_routing ─────────────────────────────
+    server.tool("update_persona_outreach_signal_routing", "Patch the outreachSignalRouting block. signal_source_field and default_signal " +
+        "are scalar — passing one replaces it. signals[] is replaced wholesale when " +
+        "passed; use add_signals / remove_signals to splice instead. " +
+        "WARNING: default_signal must be present in signals[] (API rejects otherwise). " +
+        "Removing a signal that's still referenced by an outreachTemplate.signal will " +
+        "also be rejected.", {
+        id: z.string().describe("Persona ID."),
+        signal_source_field: z
+            .string()
+            .optional()
+            .describe("Card field to read (e.g. card_signals)."),
+        default_signal: z
+            .string()
+            .optional()
+            .describe("Default signal — must exist in signals[]."),
+        signals: z
+            .array(z.string())
+            .optional()
+            .describe("Full replacement of the signals list. Mutually exclusive with add_signals / remove_signals."),
+        add_signals: z
+            .array(z.string())
+            .optional()
+            .describe("Signals to add (deduped). Mutually exclusive with signals."),
+        remove_signals: z
+            .array(z.string())
+            .optional()
+            .describe("Signals to remove. Mutually exclusive with signals."),
+    }, async ({ id, signal_source_field, default_signal, signals, add_signals, remove_signals, }) => {
+        try {
+            if (signal_source_field === undefined &&
+                default_signal === undefined &&
+                signals === undefined &&
+                add_signals === undefined &&
+                remove_signals === undefined) {
+                return toolError("Provide at least one field to update.");
+            }
+            if (signals !== undefined &&
+                (add_signals !== undefined || remove_signals !== undefined)) {
+                return toolError("'signals' is mutually exclusive with add_signals / remove_signals.");
+            }
+            const current = await fetchPersona(id);
+            const existing = asObject(current.outreachSignalRouting);
+            const next = { ...existing };
+            if (signal_source_field !== undefined)
+                next.signalSourceField = signal_source_field;
+            if (default_signal !== undefined)
+                next.defaultSignal = default_signal;
+            if (signals !== undefined) {
+                next.signals = signals;
+            }
+            else if (add_signals !== undefined || remove_signals !== undefined) {
+                const set = new Set(asArray(existing.signals));
+                for (const s of add_signals ?? [])
+                    set.add(s);
+                for (const s of remove_signals ?? [])
+                    set.delete(s);
+                next.signals = Array.from(set);
+            }
+            const data = await postPersonaUpdate(id, current.name, {
+                outreachSignalRouting: next,
+            });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_prompt_engineering ──────────────────────────────────
+    server.tool("update_persona_prompt_engineering", "Patch free-form markdown prompt fields (normalization_rules, signal_guidance, " +
+        "tone_instructions, context). Each is a separate scalar JSON column — passing " +
+        "one replaces it (pass null to clear). Other prompt fields and persona sections " +
+        "remain intact.", {
+        id: z.string().describe("Persona ID."),
+        normalization_rules: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Markdown injected into the ICP prompt. Null clears it."),
+        signal_guidance: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Markdown injected into the signal prompt. Null clears it."),
+        tone_instructions: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Markdown for voice / tone guidance. Null clears it."),
+        context: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Markdown appended to the ICP prompt. Null clears it."),
+    }, async ({ id, normalization_rules, signal_guidance, tone_instructions, context, }) => {
+        try {
+            if (normalization_rules === undefined &&
+                signal_guidance === undefined &&
+                tone_instructions === undefined &&
+                context === undefined) {
+                return toolError("Provide at least one field to update.");
+            }
+            const current = await fetchPersona(id);
+            const body = {};
+            if (normalization_rules !== undefined)
+                body.normalizationRules = normalization_rules;
+            if (signal_guidance !== undefined)
+                body.signalGuidance = signal_guidance;
+            if (tone_instructions !== undefined)
+                body.toneInstructions = tone_instructions;
+            if (context !== undefined)
+                body.context = context;
+            const data = await postPersonaUpdate(id, current.name, body);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+    // ── update_persona_icp_strategy ────────────────────────────────────────
+    server.tool("update_persona_icp_strategy", "Patch the icpStrategy JSON column. Mental map consumed verbatim by the outreach " +
+        "agent preflight: {dealType, dreamOutcome, mainPains[], keyObjections[], " +
+        "decisionDrivers[]}. Reads current icpStrategy, shallow-merges the keys you " +
+        "pass, optionally removes specified keys. Arrays (mainPains, keyObjections, " +
+        "decisionDrivers) are REPLACED wholesale when passed.", {
+        id: z.string().describe("Persona ID."),
+        dealType: z
+            .string()
+            .optional()
+            .describe("Type of deal (e.g. 'midmarket', 'enterprise', 'self-serve')."),
+        dreamOutcome: z
+            .string()
+            .optional()
+            .describe("The aspirational result the lead wants."),
+        mainPains: z
+            .array(z.string())
+            .optional()
+            .describe("Replaces the mainPains array wholesale when passed."),
+        keyObjections: z
+            .array(z.string())
+            .optional()
+            .describe("Replaces the keyObjections array wholesale when passed."),
+        decisionDrivers: z
+            .array(z.string())
+            .optional()
+            .describe("Replaces the decisionDrivers array wholesale when passed."),
+        patch: z
+            .record(z.unknown())
+            .optional()
+            .describe("Escape hatch for any additional/forward-compat keys — shallow-merged after the named fields."),
+        remove_keys: z
+            .array(z.string())
+            .optional()
+            .describe("Keys to delete from icpStrategy."),
+    }, async ({ id, dealType, dreamOutcome, mainPains, keyObjections, decisionDrivers, patch, remove_keys, }) => {
+        try {
+            if (dealType === undefined &&
+                dreamOutcome === undefined &&
+                mainPains === undefined &&
+                keyObjections === undefined &&
+                decisionDrivers === undefined &&
+                (patch === undefined || Object.keys(patch).length === 0) &&
+                (remove_keys === undefined || remove_keys.length === 0)) {
+                return toolError("Provide at least one field to update.");
+            }
+            const current = await fetchPersona(id);
+            const next = { ...asObject(current.icpStrategy) };
+            if (dealType !== undefined)
+                next.dealType = dealType;
+            if (dreamOutcome !== undefined)
+                next.dreamOutcome = dreamOutcome;
+            if (mainPains !== undefined)
+                next.mainPains = mainPains;
+            if (keyObjections !== undefined)
+                next.keyObjections = keyObjections;
+            if (decisionDrivers !== undefined)
+                next.decisionDrivers = decisionDrivers;
+            if (patch !== undefined)
+                Object.assign(next, patch);
+            for (const k of remove_keys ?? [])
+                delete next[k];
+            const data = await postPersonaUpdate(id, current.name, { icpStrategy: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
+}