refactor(contacts): add via direct POST /leads/{id}/contacts, not the import pipeline

Live testing through Claude Desktop's actual server binary revealed the
import-pipeline add path (leadbay_import_and_qualify) returns 401 on the
test account — POST /imports is rejected even with a valid token, and the
agent surfaced it as a misleading "LEADBAY_TOKEN is no longer valid" error.

The direct endpoint the web UI uses — POST /leads/{id}/contacts — works with
the SAME token (verified 200, contact created with its id). So:

- New leadbay_add_contact composite write tool wrapping POST
  /leads/{id}/contacts. One call, no import/qualify quota, accepts
  first/last name + optional job_title/linkedin_page/email/phone. Pairs with
  leadbay_remove_contact (POST /contacts/{id}/archive).
- Revert the import_and_qualify routing/recipe changes — the add-contact
  intent now routes to leadbay_add_contact instead. (Kept one incidental fix:
  a stale leadbay_research_lead -> leadbay_research_lead_by_id reference.)
- research_lead_by_id anti-trigger now points at leadbay_add_contact.
- index / _composite-file-names / TOOLS_WITH_ROUTING registration,
  WORKFLOWS row #15 + contract updated, new unit test.

Verified live through Desktop's bin.js + token: add -> contact created (no
401); remove -> archived; company back to 0 contacts. Suite green
(core 324, promptforge 16, mcp 366).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ArtyETH06

WORKFLOWS.md

@@ -26,7 +26,7 @@ The table is the human-readable index. The `yaml expected` + `yaml scenario` blo
 | 12 | **Lens extension — on-demand fill for bigger appetite** — "I want more leads on this lens / I need a bigger batch today" | `leadbay_extend_my_lens` | "I want more leads on this lens — bigger batch today" |
 | 13 | **Lens management — list / switch audiences** — "show me my lenses", "which audiences do I have", "switch to my Joinery lens" | `leadbay_my_lenses` | "Show me my lenses and switch to the Joinery one" |
 | 14 | **Lens creation — make a named audience** — "create a lens called X for sector Y", "set up a new audience" | `leadbay_new_lens` | "Create a lens called Joinery for the fintech sector" |
-| 15 | **Add a contact to a known company** — "this company has no contacts — add Jane Doe, here's her LinkedIn", "add this person I found to that lead" | `leadbay_import_and_qualify` (one `records[]` row, `CONTACT_*` fields keyed by parent `LEADBAY_ID`) | "Acme has no contacts — add Jane Doe, VP Eng, here's her LinkedIn" |
+| 15 | **Add a contact to a known company** — "this company has no contacts — add Jane Doe, here's her LinkedIn", "add this person I found to that lead" | `leadbay_add_contact` (direct `POST /leads/{id}/contacts`; pass `lead_id` + name + optional linkedin/title/email/phone) | "Acme has no contacts — add Jane Doe, VP Eng, here's her LinkedIn" |
 | 16 | **Remove a contact from a company** — "remove this contact", "delete that person, wrong one", "undo the contact I just added" | `leadbay_remove_contact` (archives by the contact's own `contact_id`) | "Remove Jane Doe from that company — I added her by mistake" |
 
 ---
@@ -241,11 +241,11 @@ prompt: "Set up a prospecting campaign for my team"
 workflow_name: Add a contact to a known company
 prompt_name: ~
 required_calls:
-  - leadbay_import_and_qualify
+  - leadbay_add_contact
 forbidden_calls:
   - leadbay_report_outreach
 success_criteria:
-  - "called leadbay_import_and_qualify with one records[] row carrying CONTACT_* fields keyed by the parent company (LEADBAY_ID / LEAD_NAME / LEAD_WEBSITE)"
+  - "called leadbay_add_contact with the parent company lead_id plus the person's name (and any linkedin/title given)"
   - "did NOT switch to an external CRM or claim Leadbay can't add contacts"
   - "did NOT call leadbay_report_outreach"
 ```

packages/core/src/composite/_composite-file-names.ts

@@ -10,6 +10,7 @@
 // that audit.
 export const COMPOSITE_FILE_TOOL_NAMES: ReadonlySet<string> = new Set([
   "leadbay_account_status",
+  "leadbay_add_contact",
   "leadbay_add_leads_to_campaign",
   "leadbay_adjust_audience",
   "leadbay_answer_clarification",

packages/core/src/composite/add-contact.ts

@@ -0,0 +1,105 @@
+import type { LeadbayClient } from "../client.js";
+import type { Tool, ToolContext } from "../types.js";
+import { leadbay_add_contact as ADD_CONTACT_DESCRIPTION } from "../tool-descriptions.generated.js";
+
+interface AddContactParams {
+  // Parent company: the lead's UUID. The created contact attaches here.
+  lead_id: string;
+  first_name: string;
+  last_name: string;
+  job_title?: string;
+  // LinkedIn profile URL — the reporter's hunch (product#3703): often the
+  // only thing a rep has for a person they found by hand.
+  linkedin_page?: string;
+  email?: string;
+  phone_number?: string;
+}
+
+interface CreatedContact {
+  id: string;
+  first_name: string | null;
+  last_name: string | null;
+  email: string | null;
+  phone_number: string | null;
+  linkedin_page: string | null;
+  job_title: string | null;
+  can_enrich?: boolean;
+  recommended?: boolean;
+  pinned?: boolean;
+}
+
+interface AddContactResult {
+  added: true;
+  lead_id: string;
+  contact: CreatedContact;
+}
+
+/**
+ * Add a single contact to a known company — the in-conversation
+ * "create_contact" the reporter asked for (leadbay/product#3703).
+ *
+ * Backend route: `POST /1.5/leads/{leadId}/contacts` → 200 with the created
+ * contact (incl. its new `id`). This is the SAME direct endpoint the Leadbay
+ * web UI uses to add a contact — distinct from, and lighter than, the CSV
+ * import pipeline (`leadbay_import_and_qualify`), which 401s on some accounts
+ * and burns import/qualify quota. One call, no quota, works.
+ *
+ * The undo is `leadbay_remove_contact` (archives by the contact's own id).
+ */
+export const addContact: Tool<AddContactParams, AddContactResult> = {
+  name: "leadbay_add_contact",
+  description: ADD_CONTACT_DESCRIPTION,
+  write: true,
+  annotations: {
+    title: "Add a contact",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      lead_id: {
+        type: "string",
+        description:
+          "UUID of the parent company (lead) to attach the contact to. The contact is created on this company.",
+      },
+      first_name: { type: "string", description: "Contact first name." },
+      last_name: { type: "string", description: "Contact last name." },
+      job_title: { type: "string", description: "Contact job title (optional)." },
+      linkedin_page: {
+        type: "string",
+        description: "Contact LinkedIn profile URL (optional).",
+      },
+      email: { type: "string", description: "Contact email (optional)." },
+      phone_number: {
+        type: "string",
+        description: "Contact phone number (optional, free-form).",
+      },
+    },
+    required: ["lead_id", "first_name", "last_name"],
+    additionalProperties: false,
+  },
+  execute: async (
+    client: LeadbayClient,
+    params: AddContactParams,
+    _ctx?: ToolContext,
+  ): Promise<AddContactResult> => {
+    const body: Record<string, unknown> = {
+      first_name: params.first_name,
+      last_name: params.last_name,
+    };
+    if (params.job_title != null) body.job_title = params.job_title;
+    if (params.linkedin_page != null) body.linkedin_page = params.linkedin_page;
+    if (params.email != null) body.email = params.email;
+    if (params.phone_number != null) body.phone_number = params.phone_number;
+
+    const contact = await client.request<CreatedContact>(
+      "POST",
+      `/leads/${params.lead_id}/contacts`,
+      body,
+    );
+    return { added: true, lead_id: params.lead_id, contact };
+  },
+};

packages/core/src/index.ts

@@ -95,6 +95,7 @@ import { bulkQualifyLeads } from "./composite/bulk-qualify-leads.js";
 import { resolveImportRows } from "./composite/resolve-import-rows.js";
 import { importLeads } from "./composite/import-leads.js";
 import { importAndQualify } from "./composite/import-and-qualify.js";
+import { addContact } from "./composite/add-contact.js";
 import { removeContact } from "./composite/remove-contact.js";
 import { importStatus } from "./composite/import-status.js";
 import { qualifyStatus } from "./composite/qualify-status.js";
@@ -293,9 +294,12 @@ export const compositeWriteTools: Tool[] = [
   reportOutreach,
   importLeads,
   importAndQualify,
-  // removeContact — the undo for the add-a-contact path. Soft-deletes
-  // (archives) a single contact via POST /contacts/{id}/archive. Default
-  // write surface so "remove this contact" works without the advanced gate.
+  // addContact / removeContact — add or remove a single person on a known
+  // company, in-conversation (product#3703). addContact wraps the direct
+  // POST /leads/{id}/contacts endpoint (same one the web UI uses — NOT the
+  // import pipeline, which 401s on some accounts). removeContact is the undo,
+  // archiving via POST /contacts/{id}/archive. Default write surface.
+  addContact,
   removeContact,
   // createCustomField is granular-shaped but file-import prompts depend on it
   // to preserve source-system links without requiring advanced-tool exposure.

packages/core/src/tool-descriptions.generated.ts

@@ -46,6 +46,48 @@ WHEN NOT TO USE: as a pre-flight gate before bulk ops — operations themselves
 `;
 // endregion: leadbay_account_status
 
+// region: leadbay_add_contact
+export const leadbay_add_contact: string = `## WHEN TO USE
+
+Trigger phrases: "add a contact to this company", "add this person to <company>", "create a contact from this LinkedIn URL", "this company has no contacts — add one", "I found someone on LinkedIn, add them to <lead>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "import these companies / a CSV of leads and qualify them" → \`leadbay_import_and_qualify\`; "get email/phone for a contact already on the company" → \`leadbay_enrich_titles\`; "remove / delete this contact" → \`leadbay_remove_contact\`.
+
+Prefer when: user wants to attach ONE known person to an already-identified company — pass the company's \`lead_id\` plus the person's name (+ optional linkedin_page/title/email/phone)
+
+Examples that SHOULD invoke this tool:
+- "Acme has no suggested contacts — add Jane Doe, VP Eng, here's her LinkedIn."
+- "Add this person I found on LinkedIn to that company."
+- "Create a contact for John Smith, CFO, on this lead."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Import these 40 domains from my CRM and qualify them."
+- "Get me the email for the contact already on this company."
+- "Remove that contact, it's the wrong person."
+
+## RENDER (quick)
+
+One-line confirmation: the contact's name + title now sits on the company.
+No table. If the contact has no email/phone yet, note it can be enriched.
+
+---
+
+Add a single contact (a person) to a known company — the in-conversation "create a contact" path. Use it when a rep has found someone (often just a LinkedIn URL) and wants them on an already-identified Leadbay company without leaving the chat.
+
+Pass the parent company's \`lead_id\` plus the person's \`first_name\` + \`last_name\`. Everything else is optional: \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\`.
+
+Backend: \`POST /leads/{lead_id}/contacts\` → returns the created contact with its new \`id\`. This is the same direct endpoint the Leadbay web UI uses — one call, no import/qualify quota. (Distinct from \`leadbay_import_and_qualify\`, which is for importing *lists of companies*, not attaching a single person.)
+
+The created contact starts unenriched — if it has no email/phone, enrich it via \`leadbay_enrich_titles\`. The undo is \`leadbay_remove_contact\` (pass the returned \`contact.id\`).
+
+Returns \`{ added: true, lead_id, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number, … } }\`.
+
+Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
+`;
+// endregion: leadbay_add_contact
+
 // region: leadbay_add_leads_to_campaign
 export const leadbay_add_leads_to_campaign: string = `## WHEN TO USE
 
@@ -1132,53 +1174,7 @@ WHEN NOT TO USE: as the first read on a lead — the leadbay_research_lead_by_id
 // endregion: leadbay_get_web_fetch
 
 // region: leadbay_import_and_qualify
-export const leadbay_import_and_qualify: string = `## WHEN TO USE
-
-Trigger phrases: "add a contact to this company", "add this person to <company>", "create a contact from this LinkedIn URL", "this company has no contacts — add one", "I found someone on LinkedIn, add them to <lead>", "import these companies and qualify them", "import this list and run AI qualification".
-
-**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
-
-Do NOT use for: "show me new leads / discovery" → \`leadbay_pull_leads\`; "deep dive on a single lead I already picked" → \`leadbay_research_lead_by_id\`; "get email/phone for a contact already on the company" → \`leadbay_enrich_titles\`.
-
-Prefer when: user wants to attach a known person (esp. a LinkedIn URL) to an already-identified company — pass one \`records[]\` row with \`CONTACT_*\` fields keyed by the parent \`LEADBAY_ID\` (else \`LEAD_NAME\`/\`LEAD_WEBSITE\`)
-
-Examples that SHOULD invoke this tool:
-- "Acme has no suggested contacts — add Jane Doe, VP Eng, here's her LinkedIn."
-- "Add this person I found on LinkedIn to that company."
-- "Import these 40 domains from my CRM and qualify them."
-
-Examples that should NOT invoke this tool (sound similar, route elsewhere):
-- "Show me today's leads."
-- "Tell me everything about that lead I just picked."
-- "Get me the email for the contact already on this company."
-
-## RENDER (quick)
-
-Use the import-result layout: summarize imported/qualified vs not-imported
-counts, then per-lead qualification answers. For a single added contact,
-confirm the person now sits on the parent company.
-
----
-
-Import + qualify leads in one call. Pass either \`domains: [{domain, name?}]\` (Mode A) OR \`records[]\` with \`mappings\` (Mode B). At least one mapped field must be LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE. Discover the org's mappable surface via \`leadbay_list_mappable_fields\`. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan → resolve → preserve → commit phases.
-
-**Add a single contact to a known company** (the "create_contact" path): this is just Mode B with one record. Map the parent company + \`CONTACT_*\` fields — the import **creates an org contact** on that company. **\`LEAD_NAME\` is required even when you pass \`LEADBAY_ID\`** — the import rejects the row with \`missing LEAD_NAME field\` otherwise. So always send both: \`LEADBAY_ID\` (the exact match key) AND \`LEAD_NAME\` (the company's display name). Minimal call:
-
-\`\`\`
-records: [{
-  LEADBAY_ID: "<lead uuid>",        // exact match key for the existing company
-  LEAD_NAME:  "SHOWROOM AUTO, LLC", // REQUIRED — send alongside LEADBAY_ID
-  CONTACT_FIRST_NAME: "Jane",
-  CONTACT_LAST_NAME:  "Doe",
-  CONTACT_TITLE:      "VP Eng",     // optional
-  CONTACT_LINKEDIN:   "https://www.linkedin.com/in/janedoe",  // optional
-  CONTACT_EMAIL:      "jane@acme.com",   // optional
-  CONTACT_PHONE_NUMBER: "+1...",         // optional
-}]
-mappings: { fields: { LEADBAY_ID: "LEADBAY_ID", LEAD_NAME: "LEAD_NAME", CONTACT_FIRST_NAME: "CONTACT_FIRST_NAME", /* … */ } }
-\`\`\`
-
-If you don't have the \`LEADBAY_ID\`, key on \`LEAD_NAME\` (+ optional \`LEAD_WEBSITE\`) alone and the import fuzzy-matches to the existing company. Repeating the same parent across rows adds multiple contacts to that one company. After the contact lands, enrich its email/phone via \`leadbay_enrich_titles\`. Use this when a rep found a person (often just a LinkedIn URL) and wants them on an already-identified Leadbay company without leaving the conversation.
+export const leadbay_import_and_qualify: string = `Import + qualify leads in one call. Pass either \`domains: [{domain, name?}]\` (Mode A) OR \`records[]\` with \`mappings\` (Mode B). At least one mapped field must be LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE. Discover the org's mappable surface via \`leadbay_list_mappable_fields\`. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan → resolve → preserve → commit phases.
 
 WHEN TO USE: agent has a list of companies (domains, or CSV-shaped rows from the user's CRM) and wants the full AI qualification — qualification answers, web-research signals — without orchestrating import + bulk_qualify_leads + lead_profile chains by hand.
 
@@ -2687,7 +2683,7 @@ Trigger phrases: "tell me about this lead", "deep dive on the lead I just picked
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
-Do NOT use for: "company name without lead id" → \`leadbay_research_lead_by_name_fuzzy\`; "draft outreach for <Contact>" → \`leadbay_prepare_outreach\`; "add a contact to this company" → \`leadbay_import_and_qualify\`.
+Do NOT use for: "company name without lead id" → \`leadbay_research_lead_by_name_fuzzy\`; "draft outreach for <Contact>" → \`leadbay_prepare_outreach\`; "add a contact to this company" → \`leadbay_add_contact\`.
 
 Prefer when: user picked a row and you have its UUID; pass \`leadId\`
 
@@ -3361,6 +3357,7 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 // Map for legacy callers; prefer importing the named constant directly.
 export const TOOL_DESCRIPTIONS = {
   leadbay_account_status,
+  leadbay_add_contact,
   leadbay_add_leads_to_campaign,
   leadbay_add_note,
   leadbay_adjust_audience,