@leadbay/mcp 0.33.1 → 0.33.3

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog — @leadbay/mcp
 
+## 0.33.3 — 2026-09-02
+
+`leadbay_pin_contact` failed 43 of its 48 production calls.
+
+Measured over the 180 days to 2026-09-02 (PostHog `mcp tool called`,
+`properties.ok = false`). Sentry issue `MCP-3A` carries exactly 43 events, so
+every `contact not found` in the `mcp` project is a pin call. 41 of the 43 are
+one scheduled agent, `zoe+dogfood@leadbay.ai`, across 12 days and MCP 0.26.0
+through 0.33.2. Its own `triggered_by` reads *"tâche planifiée : épingler le DG
+Mickael Hamot (CROMOLOGY SERVICES) à la place du président"*. It picks the DG
+out of `leadbay_research_lead_by_id` and pins that id, which on an unenriched
+company is a `source: "paid"` candidate. It has never once succeeded, and pin
+is its third most used tool.
+
+`POST /contacts/{id}/pin` resolves through `org_contacts` only
+(`OrgContactRoutes.kt:44`), so a paid candidate id can never resolve there. Two
+changes:
+
+- **The 404 now names its cause.** The client's shared 404 hint is "Verify the
+  ID is correct" (`client.ts:1048`), which on this endpoint is false: the id is
+  correct, it is the wrong namespace. An agent reads that as "look it up and
+  retry" and does, in bursts of up to 10 calls in 13 seconds. pin and unpin now
+  catch `NOT_FOUND` and replace the hint with one that names the org-vs-paid
+  split, says not to retry, and names the tools that make the person pinnable.
+- **The descriptions carry the rule.** New shared snippet
+  `snippets/heuristics/pinnable-contacts.md`, included by both templates, plus
+  the rule in `prefer_when` so it lands in the first 600 chars every host reads.
+  It also states that pinning does not steer enrichment: enrichment selects by
+  job title (`resolveAutoIncludedTitles` →
+  `paidContacts.findSimilarJobTitlesWithScores`) and `pinnedBy` plays no part.
+  That was the second half of the agent's mistake.
+
+**`pinned` is now readable.** The backend's `ContactPayload` has carried
+`pinned` + `pinned_by_ai` all along; every MCP shaping site dropped them, so a
+pin could be written but not read back except by watching `recommended`, which
+moves for other reasons too. Now passed through in `research_lead_by_id`,
+`get_contacts` and `get_lead_profile`, and marked `📌` in both markdown contact
+lists. Deliberately asymmetric: `PaidContactPayload` has no pin state, so paid
+contacts get no `pinned` key rather than a synthetic `false`.
+
+Verified live against FR staging, running the built branch:
+
+```
+BEFORE PIN:  org contact → pinned: false     paid contacts → no pinned key
+AFTER  PIN:  org contact → pinned: true      (pin http 204)
+AFTER UNPIN: org contact → pinned: false     (unpin http 204)
+```
+
+Remaining, not fixed here: on hosted an agent still has no way to enrich one
+named person. `leadbay_enrich_contacts` takes a `contact_id` and does exactly
+that, but sits in `granularWriteTools` behind `LEADBAY_MCP_ADVANCED=1`, and no
+granular tool has been called from a hosted IP in 30 days. That is why the
+agent reached for pin. Filed as leadbay/product#4050.
+
+## 0.33.2 — 2026-09-02
+
+Editing one field on a contact erased the others (product#4046).
+
+Reproduced on production while verifying leadbay/mcp#194: sending a contact's
+own current `first_name` + `last_name` + `job_title`, changing nothing, deleted
+that contact's email. The contact moved from `contacts.reachable` to
+`contacts.candidates` and `_meta.has_reachable_contact` flipped to false, so the
+lead stopped being contactable. Restored with a second call.
+
+This became reachable only the day before: until #194 the tool returned 404 on
+100% of calls, so it destroyed nothing. A tool that always failed now succeeded
+and deleted data.
+
+**The backend already had the safe behaviour and we were choosing the other
+one.** Both routes take the same payload
+(`OrgContactRoutes.kt:110,152` → `OrgContactsDaoImpl.kt:265-272`):
+
+| Route | `forceUpdateIfNullOrEmpty` | A field absent from the body |
+|---|---|---|
+| `/contacts/{id}/update` | `true` | written as null — **erased** |
+| `/contacts/{id}/merge` | `false` | skipped — **kept** |
+
+So the fix needs no read-modify-write, no extra round-trip and no race window.
+`leadbay_update_contact` now routes by intent:
+
+- **Nothing being erased → `/merge`.** Every field the caller omitted survives.
+- **Any field passed as `null` → `/update`**, which rewrites the record — so
+  that call must carry all four optional fields. If it does not, the tool
+  refuses with `CONTACT_CLEAR_NEEDS_FULL_RECORD` rather than deleting what was
+  not mentioned. The destructive path costs more effort than the safe one,
+  which is the intended asymmetry.
+- The result carries `mode` (`merge` / `replace`), `preserved` and `cleared`, so
+  a wrong edit is visible rather than silent.
+
+Verified live on staging, same body to each route:
+
+```
+POST /contacts/{id}/merge   {first_name, last_name, job_title:"CEO"}
+  → job_title CEO,  email merge.probe@example.test,  phone +15550001111   (kept)
+POST /contacts/{id}/update  {first_name, last_name, job_title:"CTO"}
+  → job_title CTO,  email absent,  phone absent                           (erased)
+```
+
+Two existing test files were changed rather than added, because both asserted
+the contract this fixes: `update-contact.test.ts`'s happy path now expects
+`/merge`, and `update-contact-null-clear.test.ts`'s clear case now supplies the
+whole record. The second had encoded the data loss as correct — it asserted that
+unmentioned fields are not sent, while posting to the route that deletes them.
+
 ## 0.33.1 — 2026-09-02
 
 Follow-up to 0.32.0 (product#4007). A review finding landed after the merge.

package/dist/bin.js

@@ -3688,7 +3688,7 @@ Trigger phrases: "pin this contact", "mark this person as priority", "make this
 
 Do NOT use for: "unpin / remove the pin" \u2192 \`leadbay_unpin_contact\`; "add a contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`.
 
-Prefer when: user wants ONE person flagged as the priority on a company \u2014 pass that contact's own \`contact_id\`
+Prefer when: user wants ONE person flagged as the priority on a company \u2014 pass that contact's own \`contact_id\`, and ONLY a \`source:"org"\` contact can be pinned (a \`source:"paid"\` candidate returns 'contact not found')
 
 Examples that SHOULD invoke this tool:
 - "Pin Jane Doe as the main contact on this company."
@@ -3710,9 +3710,24 @@ Pin a single contact on a company so it surfaces first as a priority / favourite
 
 Pass the contact's **own** \`contact_id\` (the \`id\` field on a contact object from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
 
+**Only \`source: "org"\` contacts are pinnable.** Every contact returned by \`leadbay_research_lead_by_id\` carries a \`source\` field, and the two sources are separate id namespaces on the backend:
+
+- \`source: "org"\` \u2014 a row in your organization's own contact directory. Pinnable. Also carries \`pinned\` (true when someone has pinned it) and \`pinned_by_ai\` (true when Leadbay's AI pinned it rather than a human).
+- \`source: "paid"\` \u2014 an enrichment *candidate* (the \`candidates\` bucket): a person Leadbay suggests but has not yet resolved into your directory. NOT pinnable, and carries no \`pinned\` field at all.
+
+Passing a \`source: "paid"\` id here returns **\`contact not found\`**. That is the expected answer for a candidate, not an outage and not a transient error: nothing is broken, the person is simply not an org contact yet. Do not retry, do not re-fetch the lead hoping for a different result, and do not tell the user that pinning is failing or unavailable.
+
+To pin someone who is currently only a candidate, first make them an org contact:
+
+- \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) resolves the candidate and writes a NEW org contact for that person. It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row.
+- Or add them directly with \`leadbay_add_contact\`, which returns the new org contact's \`id\` \u2014 that id is pinnable immediately.
+
+**Pinning does not steer enrichment.** It only marks who the priority is on a company the user already has. Enrichment picks people by JOB TITLE, so "enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_titles\` with the wanted title \u2014 not a pin. Pinning first and enriching after changes nothing about who gets enriched.
+
+
 Backend: \`POST /contacts/{contact_id}/pin\` \u2192 204. Idempotent. The inverse is \`leadbay_unpin_contact\`.
 
-Returns \`{ pinned: true, contact_id, action: "pinned" }\`.
+Returns \`{ pinned: true, contact_id, action: "pinned" }\`. To read the resulting state back, re-call \`leadbay_research_lead_by_id\` \u2014 the pinned contact's \`pinned\` flips to \`true\` and it becomes the lead's \`recommended\` contact.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -5657,7 +5672,7 @@ Trigger phrases: "unpin this contact", "remove the pin from this contact", "this
 
 Do NOT use for: "pin / mark as priority" \u2192 \`leadbay_pin_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`.
 
-Prefer when: user wants to clear the pinned flag on a contact (but keep the contact) \u2014 pass that contact's own \`contact_id\`
+Prefer when: user wants to clear the pinned flag on a contact (but keep the contact) \u2014 pass that contact's own \`contact_id\`, and ONLY a \`source:"org"\` contact can be unpinned (a \`source:"paid"\` candidate returns 'contact not found')
 
 Examples that SHOULD invoke this tool:
 - "Unpin Jane Doe \u2014 she's not the priority anymore."
@@ -5680,9 +5695,26 @@ Unpin a single contact on a company \u2014 clears its priority / favourite flag.
 
 Pass the contact's **own** \`contact_id\` \u2014 not the parent lead id.
 
+**Only \`source: "org"\` contacts are pinnable.** Every contact returned by \`leadbay_research_lead_by_id\` carries a \`source\` field, and the two sources are separate id namespaces on the backend:
+
+- \`source: "org"\` \u2014 a row in your organization's own contact directory. Pinnable. Also carries \`pinned\` (true when someone has pinned it) and \`pinned_by_ai\` (true when Leadbay's AI pinned it rather than a human).
+- \`source: "paid"\` \u2014 an enrichment *candidate* (the \`candidates\` bucket): a person Leadbay suggests but has not yet resolved into your directory. NOT pinnable, and carries no \`pinned\` field at all.
+
+Passing a \`source: "paid"\` id here returns **\`contact not found\`**. That is the expected answer for a candidate, not an outage and not a transient error: nothing is broken, the person is simply not an org contact yet. Do not retry, do not re-fetch the lead hoping for a different result, and do not tell the user that pinning is failing or unavailable.
+
+To pin someone who is currently only a candidate, first make them an org contact:
+
+- \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) resolves the candidate and writes a NEW org contact for that person. It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row.
+- Or add them directly with \`leadbay_add_contact\`, which returns the new org contact's \`id\` \u2014 that id is pinnable immediately.
+
+**Pinning does not steer enrichment.** It only marks who the priority is on a company the user already has. Enrichment picks people by JOB TITLE, so "enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_titles\` with the wanted title \u2014 not a pin. Pinning first and enriching after changes nothing about who gets enriched.
+
+
+A \`source: "org"\` contact that was never pinned is a no-op here, not an error \u2014 the backend answers 204 either way. Check \`pinned\` on the contact before calling if you need to tell the user whether anything actually changed.
+
 Backend: \`POST /contacts/{contact_id}/unpin\` \u2192 204. Idempotent. The inverse is \`leadbay_pin_contact\`.
 
-Returns \`{ pinned: false, contact_id, action: "unpinned" }\`.
+Returns \`{ pinned: false, contact_id, action: "unpinned" }\`. To read the resulting state back, re-call \`leadbay_research_lead_by_id\` \u2014 the contact's \`pinned\` flips to \`false\` and the lead's \`recommended\` contact reverts to the title-matched default.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -5692,7 +5724,7 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass its \`contact_id\`, first_name, last_name and only the fields being changed
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -5725,11 +5757,30 @@ Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
 
 A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
-**\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
+## Omitting a field keeps it. Erasing one takes an explicit \`null\`.
+
+Send only what you are changing. Any field you leave out keeps its current value \u2014 you do NOT need to read the contact first and echo everything back.
+
+\`\`\`
+{ contact_id, first_name, last_name, job_title: "CEO" }
+\u2192 title becomes CEO. email, phone and LinkedIn are untouched.
+\`\`\`
+
+**To erase a field, pass it as \`null\`.** Because erasing rewrites the whole record, that call must carry ALL of \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\` \u2014 current value for the ones to keep, \`null\` for the ones to erase. If any are missing the call is refused with \`CONTACT_CLEAR_NEEDS_FULL_RECORD\` rather than deleting them; read the contact with \`leadbay_research_lead_by_id\` and re-call.
+
+\`\`\`
+{ contact_id, first_name, last_name, email: null,
+  job_title: "CEO", phone_number: "+33\u2026", linkedin_page: "https://\u2026" }
+\u2192 email erased, everything else as given.
+\`\`\`
+
+\`first_name\` + \`last_name\` are required on every call. The backend validates the contact's identity and rejects a body without them (\`invalid contact\`), so pass the current values when you are not changing the name.
 
-Backend: \`POST /contacts/{contact_id}/update\` (snake_case body) \u2192 200 with the updated contact. Edits in place (same id). Camel-case bodies are rejected.
+The result tells you which happened: \`mode\` is \`merge\` or \`replace\`, \`preserved\` lists the fields left untouched, \`cleared\` lists the fields erased. **Check \`cleared\` is what you intended.**
 
-Returns \`{ updated: true, contact_id, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
+Backend: \`POST /contacts/{contact_id}/merge\` when nothing is being erased, \`POST /contacts/{contact_id}/update\` when something is. Snake_case body; camel-case is rejected. Edits in place (same id).
+
+Returns \`{ updated: true, contact_id, mode, preserved, cleared, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -6067,6 +6118,10 @@ var init_get_lead_profile = __esm({
             job_title: c.job_title,
             recommended: c.recommended,
             enrichment: c.enrichment,
+            // Org contacts only — the backend's PaidContactPayload carries no pin
+            // state, because a paid candidate cannot be pinned.
+            pinned: c.pinned ?? false,
+            pinned_by_ai: c.pinned_by_ai ?? false,
             source: "org"
           })),
           ...paidContacts.map((c) => ({
@@ -6158,7 +6213,7 @@ var init_get_contacts = __esm({
         properties: {
           contacts: {
             type: "array",
-            description: "Merged org+paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}.",
+            description: "Merged org+paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}. `source:'org'` entries additionally carry {pinned, pinned_by_ai}; `source:'paid'` entries do not, because a paid candidate cannot be pinned \u2014 passing its id to leadbay_pin_contact / leadbay_unpin_contact returns NOT_FOUND.",
             items: {
               type: "object",
               properties: {
@@ -6170,6 +6225,14 @@ var init_get_contacts = __esm({
                 linkedin_page: { type: ["string", "null"] },
                 job_title: { type: ["string", "null"] },
                 recommended: { type: "boolean" },
+                pinned: {
+                  type: "boolean",
+                  description: "Someone flagged this person as the priority on the company. Present on source:'org' contacts only."
+                },
+                pinned_by_ai: {
+                  type: "boolean",
+                  description: "The pin came from Leadbay's AI rather than a human. Present on source:'org' contacts only."
+                },
                 source: { type: "string", enum: ["org", "paid"] },
                 enrichment: {
                   type: ["object", "null"],
@@ -6228,6 +6291,10 @@ var init_get_contacts = __esm({
               job_title: c.job_title,
               recommended: c.recommended,
               enrichment: c.enrichment,
+              // Org contacts only — the backend's PaidContactPayload carries no
+              // pin state, because a paid candidate cannot be pinned.
+              pinned: c.pinned ?? false,
+              pinned_by_ai: c.pinned_by_ai ?? false,
               source: "org"
             })),
             ...paidContacts.map((c) => ({
@@ -11766,11 +11833,12 @@ var init_remove_contact = __esm({
 });
 
 // ../core/dist/tools/pin-contact.js
-var pinContact;
+var NOT_PINNABLE_HINT, pinContact;
 var init_pin_contact = __esm({
   "../core/dist/tools/pin-contact.js"() {
     "use strict";
     init_tool_descriptions_generated();
+    NOT_PINNABLE_HINT = 'This contact id is not in your organization\'s contact directory, so it cannot be pinned or unpinned. Almost always it is a `source: "paid"` enrichment candidate from leadbay_research_lead_by_id\'s `candidates` list; only `source: "org"` contacts are pinnable. The id is not wrong and the tool is not broken, so do NOT retry it. To act on this person, enrich them by job title with leadbay_enrich_titles, or add them with leadbay_add_contact \u2014 either produces a NEW org contact with a different id, which is pinnable. Note that pinning does not decide who gets enriched; enrichment selects people by job title.';
     pinContact = {
       name: "leadbay_pin_contact",
       description: leadbay_pin_contact,
@@ -11794,7 +11862,13 @@ var init_pin_contact = __esm({
         additionalProperties: false
       },
       execute: async (client, params, _ctx) => {
-        await client.requestVoid("POST", `/contacts/${params.contact_id}/pin`);
+        try {
+          await client.requestVoid("POST", `/contacts/${params.contact_id}/pin`);
+        } catch (e) {
+          if (e?.code === "NOT_FOUND")
+            throw { ...e, hint: NOT_PINNABLE_HINT };
+          throw e;
+        }
         return { pinned: true, contact_id: params.contact_id, action: "pinned" };
       }
     };
@@ -11807,6 +11881,7 @@ var init_unpin_contact = __esm({
   "../core/dist/tools/unpin-contact.js"() {
     "use strict";
     init_tool_descriptions_generated();
+    init_pin_contact();
     unpinContact = {
       name: "leadbay_unpin_contact",
       description: leadbay_unpin_contact,
@@ -11830,7 +11905,13 @@ var init_unpin_contact = __esm({
         additionalProperties: false
       },
       execute: async (client, params, _ctx) => {
-        await client.requestVoid("POST", `/contacts/${params.contact_id}/unpin`);
+        try {
+          await client.requestVoid("POST", `/contacts/${params.contact_id}/unpin`);
+        } catch (e) {
+          if (e?.code === "NOT_FOUND")
+            throw { ...e, hint: NOT_PINNABLE_HINT };
+          throw e;
+        }
         return { pinned: false, contact_id: params.contact_id, action: "unpinned" };
       }
     };
@@ -11873,39 +11954,59 @@ var init_update_contact = __esm({
           // new value. execute forwards null verbatim; the backend accepts it.
           job_title: {
             type: ["string", "null"],
-            description: "Contact job title. Pass null to clear it."
+            description: "Contact job title. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           linkedin_page: {
             type: ["string", "null"],
-            description: "Contact LinkedIn URL. Pass null to clear it."
+            description: "Contact LinkedIn URL. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           email: {
             type: ["string", "null"],
-            description: "Contact email. Pass null to clear it."
+            description: "Contact email. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           phone_number: {
             type: ["string", "null"],
-            description: "Contact phone (free-form). Pass null to clear it."
+            description: "Contact phone (free-form). Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           }
         },
         required: ["contact_id", "first_name", "last_name"],
         additionalProperties: false
       },
       execute: async (client, params, _ctx) => {
+        const OPTIONAL = ["job_title", "linkedin_page", "email", "phone_number"];
+        const asked = (f) => params[f] !== void 0;
+        const clearing = OPTIONAL.filter((f) => params[f] === null);
         const body = {
           first_name: params.first_name,
           last_name: params.last_name
         };
-        if (params.job_title !== void 0)
-          body.job_title = params.job_title;
-        if (params.linkedin_page !== void 0)
-          body.linkedin_page = params.linkedin_page;
-        if (params.email !== void 0)
-          body.email = params.email;
-        if (params.phone_number !== void 0)
-          body.phone_number = params.phone_number;
+        for (const f of OPTIONAL)
+          if (asked(f))
+            body[f] = params[f];
+        if (clearing.length === 0) {
+          const contact2 = await client.request("POST", `/contacts/${params.contact_id}/merge`, body);
+          return {
+            updated: true,
+            contact_id: params.contact_id,
+            contact: contact2,
+            mode: "merge",
+            preserved: OPTIONAL.filter((f) => !asked(f)),
+            cleared: []
+          };
+        }
+        const missing = OPTIONAL.filter((f) => !asked(f));
+        if (missing.length > 0) {
+          throw client.makeError("CONTACT_CLEAR_NEEDS_FULL_RECORD", `Clearing ${clearing.join(", ")} rewrites the whole contact, and ${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} not supplied`, `Read the contact (leadbay_research_lead_by_id) and re-call with ALL of ${OPTIONAL.join(", ")} \u2014 current value to keep it, null to clear it. Omitting a field here would delete it.`, `POST /contacts/${params.contact_id}/update`);
+        }
         const contact = await client.request("POST", `/contacts/${params.contact_id}/update`, body);
-        return { updated: true, contact_id: params.contact_id, contact };
+        return {
+          updated: true,
+          contact_id: params.contact_id,
+          contact,
+          mode: "replace",
+          preserved: [],
+          cleared: clearing
+        };
       }
     };
   }
@@ -13926,7 +14027,8 @@ ${firm.short_description}`);
       const ln = c.last_name ?? "";
       const title = c.job_title ?? "\u2014";
       const channel = c.email ?? c.phone_number ?? "\u2014";
-      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${channel}`);
+      const pin = c.pinned ? " \u{1F4CC}" : "";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}**${pin} \u2014 ${title} \xB7 ${channel}`);
     }
   }
   const candidates = Array.isArray(contacts.candidates) ? contacts.candidates : [];
@@ -13938,7 +14040,8 @@ ${firm.short_description}`);
       const ln = c.last_name ?? "";
       const title = c.job_title ?? "\u2014";
       const li = c.linkedin_page ? `LinkedIn` : "no LinkedIn";
-      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${li}`);
+      const pin = c.pinned ? " \u{1F4CC}" : "";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}**${pin} \u2014 ${title} \xB7 ${li}`);
     }
     if (candidates.length > 10)
       out.push(`- _${candidates.length - 10} more \u2026_`);
@@ -14150,7 +14253,7 @@ var init_research_lead_by_id = __esm({
           },
           contacts: {
             type: "object",
-            description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
+            description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact / leadbay_pin_contact / leadbay_unpin_contact \u2014 a `"paid"` id returns NOT_FOUND there, which means "this candidate is not an org contact yet", NOT that the tool is broken. Only `source:"org"` contacts carry `pinned` (someone flagged this person as the priority) and `pinned_by_ai` (that someone was Leadbay\'s AI, not a human); paid candidates have no pin state because they cannot be pinned.',
             properties: {
               reachable: { type: "array", items: { type: "object" } },
               candidates: { type: "array", items: { type: "object" } }
@@ -14275,6 +14378,12 @@ var init_research_lead_by_id = __esm({
           linkedin_page: normalizeLinkedinPage5(c.linkedin_page ?? null),
           recommended: c.recommended,
           enrichment_done: true,
+          // Pin state exists on org contacts only — mirror the backend, which
+          // omits it entirely from PaidContactPayload. `pinned` is what makes a
+          // pin readable at all; without it the agent can only infer the pin from
+          // `recommended`, which also moves for non-pin reasons.
+          pinned: c.pinned ?? false,
+          pinned_by_ai: c.pinned_by_ai ?? false,
           source: "org"
         });
         const allContacts = [
@@ -27862,7 +27971,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.33.1";
+var VERSION = "0.33.3";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -6279,7 +6279,7 @@ Trigger phrases: "pin this contact", "mark this person as priority", "make this
 
 Do NOT use for: "unpin / remove the pin" \u2192 \`leadbay_unpin_contact\`; "add a contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`.
 
-Prefer when: user wants ONE person flagged as the priority on a company \u2014 pass that contact's own \`contact_id\`
+Prefer when: user wants ONE person flagged as the priority on a company \u2014 pass that contact's own \`contact_id\`, and ONLY a \`source:"org"\` contact can be pinned (a \`source:"paid"\` candidate returns 'contact not found')
 
 Examples that SHOULD invoke this tool:
 - "Pin Jane Doe as the main contact on this company."
@@ -6301,9 +6301,24 @@ Pin a single contact on a company so it surfaces first as a priority / favourite
 
 Pass the contact's **own** \`contact_id\` (the \`id\` field on a contact object from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
 
+**Only \`source: "org"\` contacts are pinnable.** Every contact returned by \`leadbay_research_lead_by_id\` carries a \`source\` field, and the two sources are separate id namespaces on the backend:
+
+- \`source: "org"\` \u2014 a row in your organization's own contact directory. Pinnable. Also carries \`pinned\` (true when someone has pinned it) and \`pinned_by_ai\` (true when Leadbay's AI pinned it rather than a human).
+- \`source: "paid"\` \u2014 an enrichment *candidate* (the \`candidates\` bucket): a person Leadbay suggests but has not yet resolved into your directory. NOT pinnable, and carries no \`pinned\` field at all.
+
+Passing a \`source: "paid"\` id here returns **\`contact not found\`**. That is the expected answer for a candidate, not an outage and not a transient error: nothing is broken, the person is simply not an org contact yet. Do not retry, do not re-fetch the lead hoping for a different result, and do not tell the user that pinning is failing or unavailable.
+
+To pin someone who is currently only a candidate, first make them an org contact:
+
+- \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) resolves the candidate and writes a NEW org contact for that person. It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row.
+- Or add them directly with \`leadbay_add_contact\`, which returns the new org contact's \`id\` \u2014 that id is pinnable immediately.
+
+**Pinning does not steer enrichment.** It only marks who the priority is on a company the user already has. Enrichment picks people by JOB TITLE, so "enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_titles\` with the wanted title \u2014 not a pin. Pinning first and enriching after changes nothing about who gets enriched.
+
+
 Backend: \`POST /contacts/{contact_id}/pin\` \u2192 204. Idempotent. The inverse is \`leadbay_unpin_contact\`.
 
-Returns \`{ pinned: true, contact_id, action: "pinned" }\`.
+Returns \`{ pinned: true, contact_id, action: "pinned" }\`. To read the resulting state back, re-call \`leadbay_research_lead_by_id\` \u2014 the pinned contact's \`pinned\` flips to \`true\` and it becomes the lead's \`recommended\` contact.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -8248,7 +8263,7 @@ Trigger phrases: "unpin this contact", "remove the pin from this contact", "this
 
 Do NOT use for: "pin / mark as priority" \u2192 \`leadbay_pin_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`.
 
-Prefer when: user wants to clear the pinned flag on a contact (but keep the contact) \u2014 pass that contact's own \`contact_id\`
+Prefer when: user wants to clear the pinned flag on a contact (but keep the contact) \u2014 pass that contact's own \`contact_id\`, and ONLY a \`source:"org"\` contact can be unpinned (a \`source:"paid"\` candidate returns 'contact not found')
 
 Examples that SHOULD invoke this tool:
 - "Unpin Jane Doe \u2014 she's not the priority anymore."
@@ -8271,9 +8286,26 @@ Unpin a single contact on a company \u2014 clears its priority / favourite flag.
 
 Pass the contact's **own** \`contact_id\` \u2014 not the parent lead id.
 
+**Only \`source: "org"\` contacts are pinnable.** Every contact returned by \`leadbay_research_lead_by_id\` carries a \`source\` field, and the two sources are separate id namespaces on the backend:
+
+- \`source: "org"\` \u2014 a row in your organization's own contact directory. Pinnable. Also carries \`pinned\` (true when someone has pinned it) and \`pinned_by_ai\` (true when Leadbay's AI pinned it rather than a human).
+- \`source: "paid"\` \u2014 an enrichment *candidate* (the \`candidates\` bucket): a person Leadbay suggests but has not yet resolved into your directory. NOT pinnable, and carries no \`pinned\` field at all.
+
+Passing a \`source: "paid"\` id here returns **\`contact not found\`**. That is the expected answer for a candidate, not an outage and not a transient error: nothing is broken, the person is simply not an org contact yet. Do not retry, do not re-fetch the lead hoping for a different result, and do not tell the user that pinning is failing or unavailable.
+
+To pin someone who is currently only a candidate, first make them an org contact:
+
+- \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) resolves the candidate and writes a NEW org contact for that person. It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row.
+- Or add them directly with \`leadbay_add_contact\`, which returns the new org contact's \`id\` \u2014 that id is pinnable immediately.
+
+**Pinning does not steer enrichment.** It only marks who the priority is on a company the user already has. Enrichment picks people by JOB TITLE, so "enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_titles\` with the wanted title \u2014 not a pin. Pinning first and enriching after changes nothing about who gets enriched.
+
+
+A \`source: "org"\` contact that was never pinned is a no-op here, not an error \u2014 the backend answers 204 either way. Check \`pinned\` on the contact before calling if you need to tell the user whether anything actually changed.
+
 Backend: \`POST /contacts/{contact_id}/unpin\` \u2192 204. Idempotent. The inverse is \`leadbay_pin_contact\`.
 
-Returns \`{ pinned: false, contact_id, action: "unpinned" }\`.
+Returns \`{ pinned: false, contact_id, action: "unpinned" }\`. To read the resulting state back, re-call \`leadbay_research_lead_by_id\` \u2014 the contact's \`pinned\` flips to \`false\` and the lead's \`recommended\` contact reverts to the title-matched default.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -8283,7 +8315,7 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass its \`contact_id\`, first_name, last_name and only the fields being changed
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -8316,11 +8348,30 @@ Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
 
 A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
-**\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
+## Omitting a field keeps it. Erasing one takes an explicit \`null\`.
+
+Send only what you are changing. Any field you leave out keeps its current value \u2014 you do NOT need to read the contact first and echo everything back.
+
+\`\`\`
+{ contact_id, first_name, last_name, job_title: "CEO" }
+\u2192 title becomes CEO. email, phone and LinkedIn are untouched.
+\`\`\`
+
+**To erase a field, pass it as \`null\`.** Because erasing rewrites the whole record, that call must carry ALL of \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\` \u2014 current value for the ones to keep, \`null\` for the ones to erase. If any are missing the call is refused with \`CONTACT_CLEAR_NEEDS_FULL_RECORD\` rather than deleting them; read the contact with \`leadbay_research_lead_by_id\` and re-call.
+
+\`\`\`
+{ contact_id, first_name, last_name, email: null,
+  job_title: "CEO", phone_number: "+33\u2026", linkedin_page: "https://\u2026" }
+\u2192 email erased, everything else as given.
+\`\`\`
+
+\`first_name\` + \`last_name\` are required on every call. The backend validates the contact's identity and rejects a body without them (\`invalid contact\`), so pass the current values when you are not changing the name.
+
+The result tells you which happened: \`mode\` is \`merge\` or \`replace\`, \`preserved\` lists the fields left untouched, \`cleared\` lists the fields erased. **Check \`cleared\` is what you intended.**
 
-Backend: \`POST /contacts/{contact_id}/update\` (snake_case body) \u2192 200 with the updated contact. Edits in place (same id). Camel-case bodies are rejected.
+Backend: \`POST /contacts/{contact_id}/merge\` when nothing is being erased, \`POST /contacts/{contact_id}/update\` when something is. Snake_case body; camel-case is rejected. Edits in place (same id).
 
-Returns \`{ updated: true, contact_id, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
+Returns \`{ updated: true, contact_id, mode, preserved, cleared, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -8629,6 +8680,10 @@ var getLeadProfile = {
         job_title: c.job_title,
         recommended: c.recommended,
         enrichment: c.enrichment,
+        // Org contacts only — the backend's PaidContactPayload carries no pin
+        // state, because a paid candidate cannot be pinned.
+        pinned: c.pinned ?? false,
+        pinned_by_ai: c.pinned_by_ai ?? false,
         source: "org"
       })),
       ...paidContacts.map((c) => ({
@@ -8713,7 +8768,7 @@ var getContacts = {
     properties: {
       contacts: {
         type: "array",
-        description: "Merged org+paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}.",
+        description: "Merged org+paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}. `source:'org'` entries additionally carry {pinned, pinned_by_ai}; `source:'paid'` entries do not, because a paid candidate cannot be pinned \u2014 passing its id to leadbay_pin_contact / leadbay_unpin_contact returns NOT_FOUND.",
         items: {
           type: "object",
           properties: {
@@ -8725,6 +8780,14 @@ var getContacts = {
             linkedin_page: { type: ["string", "null"] },
             job_title: { type: ["string", "null"] },
             recommended: { type: "boolean" },
+            pinned: {
+              type: "boolean",
+              description: "Someone flagged this person as the priority on the company. Present on source:'org' contacts only."
+            },
+            pinned_by_ai: {
+              type: "boolean",
+              description: "The pin came from Leadbay's AI rather than a human. Present on source:'org' contacts only."
+            },
             source: { type: "string", enum: ["org", "paid"] },
             enrichment: {
               type: ["object", "null"],
@@ -8783,6 +8846,10 @@ var getContacts = {
           job_title: c.job_title,
           recommended: c.recommended,
           enrichment: c.enrichment,
+          // Org contacts only — the backend's PaidContactPayload carries no
+          // pin state, because a paid candidate cannot be pinned.
+          pinned: c.pinned ?? false,
+          pinned_by_ai: c.pinned_by_ai ?? false,
           source: "org"
         })),
         ...paidContacts.map((c) => ({
@@ -13912,6 +13979,7 @@ var removeContact = {
 };
 
 // ../core/dist/tools/pin-contact.js
+var NOT_PINNABLE_HINT = 'This contact id is not in your organization\'s contact directory, so it cannot be pinned or unpinned. Almost always it is a `source: "paid"` enrichment candidate from leadbay_research_lead_by_id\'s `candidates` list; only `source: "org"` contacts are pinnable. The id is not wrong and the tool is not broken, so do NOT retry it. To act on this person, enrich them by job title with leadbay_enrich_titles, or add them with leadbay_add_contact \u2014 either produces a NEW org contact with a different id, which is pinnable. Note that pinning does not decide who gets enriched; enrichment selects people by job title.';
 var pinContact = {
   name: "leadbay_pin_contact",
   description: leadbay_pin_contact,
@@ -13935,7 +14003,13 @@ var pinContact = {
     additionalProperties: false
   },
   execute: async (client, params, _ctx) => {
-    await client.requestVoid("POST", `/contacts/${params.contact_id}/pin`);
+    try {
+      await client.requestVoid("POST", `/contacts/${params.contact_id}/pin`);
+    } catch (e) {
+      if (e?.code === "NOT_FOUND")
+        throw { ...e, hint: NOT_PINNABLE_HINT };
+      throw e;
+    }
     return { pinned: true, contact_id: params.contact_id, action: "pinned" };
   }
 };
@@ -13964,7 +14038,13 @@ var unpinContact = {
     additionalProperties: false
   },
   execute: async (client, params, _ctx) => {
-    await client.requestVoid("POST", `/contacts/${params.contact_id}/unpin`);
+    try {
+      await client.requestVoid("POST", `/contacts/${params.contact_id}/unpin`);
+    } catch (e) {
+      if (e?.code === "NOT_FOUND")
+        throw { ...e, hint: NOT_PINNABLE_HINT };
+      throw e;
+    }
     return { pinned: false, contact_id: params.contact_id, action: "unpinned" };
   }
 };
@@ -14000,39 +14080,59 @@ var updateContact = {
       // new value. execute forwards null verbatim; the backend accepts it.
       job_title: {
         type: ["string", "null"],
-        description: "Contact job title. Pass null to clear it."
+        description: "Contact job title. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       linkedin_page: {
         type: ["string", "null"],
-        description: "Contact LinkedIn URL. Pass null to clear it."
+        description: "Contact LinkedIn URL. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       email: {
         type: ["string", "null"],
-        description: "Contact email. Pass null to clear it."
+        description: "Contact email. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       phone_number: {
         type: ["string", "null"],
-        description: "Contact phone (free-form). Pass null to clear it."
+        description: "Contact phone (free-form). Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       }
     },
     required: ["contact_id", "first_name", "last_name"],
     additionalProperties: false
   },
   execute: async (client, params, _ctx) => {
+    const OPTIONAL = ["job_title", "linkedin_page", "email", "phone_number"];
+    const asked = (f) => params[f] !== void 0;
+    const clearing = OPTIONAL.filter((f) => params[f] === null);
     const body = {
       first_name: params.first_name,
       last_name: params.last_name
     };
-    if (params.job_title !== void 0)
-      body.job_title = params.job_title;
-    if (params.linkedin_page !== void 0)
-      body.linkedin_page = params.linkedin_page;
-    if (params.email !== void 0)
-      body.email = params.email;
-    if (params.phone_number !== void 0)
-      body.phone_number = params.phone_number;
+    for (const f of OPTIONAL)
+      if (asked(f))
+        body[f] = params[f];
+    if (clearing.length === 0) {
+      const contact2 = await client.request("POST", `/contacts/${params.contact_id}/merge`, body);
+      return {
+        updated: true,
+        contact_id: params.contact_id,
+        contact: contact2,
+        mode: "merge",
+        preserved: OPTIONAL.filter((f) => !asked(f)),
+        cleared: []
+      };
+    }
+    const missing = OPTIONAL.filter((f) => !asked(f));
+    if (missing.length > 0) {
+      throw client.makeError("CONTACT_CLEAR_NEEDS_FULL_RECORD", `Clearing ${clearing.join(", ")} rewrites the whole contact, and ${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} not supplied`, `Read the contact (leadbay_research_lead_by_id) and re-call with ALL of ${OPTIONAL.join(", ")} \u2014 current value to keep it, null to clear it. Omitting a field here would delete it.`, `POST /contacts/${params.contact_id}/update`);
+    }
     const contact = await client.request("POST", `/contacts/${params.contact_id}/update`, body);
-    return { updated: true, contact_id: params.contact_id, contact };
+    return {
+      updated: true,
+      contact_id: params.contact_id,
+      contact,
+      mode: "replace",
+      preserved: [],
+      cleared: clearing
+    };
   }
 };
 
@@ -15938,7 +16038,8 @@ ${firm.short_description}`);
       const ln = c.last_name ?? "";
       const title = c.job_title ?? "\u2014";
       const channel = c.email ?? c.phone_number ?? "\u2014";
-      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${channel}`);
+      const pin = c.pinned ? " \u{1F4CC}" : "";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}**${pin} \u2014 ${title} \xB7 ${channel}`);
     }
   }
   const candidates = Array.isArray(contacts.candidates) ? contacts.candidates : [];
@@ -15950,7 +16051,8 @@ ${firm.short_description}`);
       const ln = c.last_name ?? "";
       const title = c.job_title ?? "\u2014";
       const li = c.linkedin_page ? `LinkedIn` : "no LinkedIn";
-      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${li}`);
+      const pin = c.pinned ? " \u{1F4CC}" : "";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}**${pin} \u2014 ${title} \xB7 ${li}`);
     }
     if (candidates.length > 10)
       out.push(`- _${candidates.length - 10} more \u2026_`);
@@ -16156,7 +16258,7 @@ var researchLeadById = {
       },
       contacts: {
         type: "object",
-        description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
+        description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact / leadbay_pin_contact / leadbay_unpin_contact \u2014 a `"paid"` id returns NOT_FOUND there, which means "this candidate is not an org contact yet", NOT that the tool is broken. Only `source:"org"` contacts carry `pinned` (someone flagged this person as the priority) and `pinned_by_ai` (that someone was Leadbay\'s AI, not a human); paid candidates have no pin state because they cannot be pinned.',
         properties: {
           reachable: { type: "array", items: { type: "object" } },
           candidates: { type: "array", items: { type: "object" } }
@@ -16281,6 +16383,12 @@ var researchLeadById = {
       linkedin_page: normalizeLinkedinPage5(c.linkedin_page ?? null),
       recommended: c.recommended,
       enrichment_done: true,
+      // Pin state exists on org contacts only — mirror the backend, which
+      // omits it entirely from PaidContactPayload. `pinned` is what makes a
+      // pin readable at all; without it the agent can only infer the pin from
+      // `recommended`, which also moves for non-pin reasons.
+      pinned: c.pinned ?? false,
+      pinned_by_ai: c.pinned_by_ai ?? false,
       source: "org"
     });
     const allContacts = [
@@ -24629,7 +24737,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.33.1" : "0.0.0-dev";
+var VERSION = true ? "0.33.3" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var logger = {

package/dist/installer-electron.js

@@ -1804,7 +1804,7 @@ var init_installer_gui = __esm({
     init_install_dxt();
     init_install_shared();
     init_oauth();
-    VERSION = true ? "0.33.1" : "0.0.0-dev";
+    VERSION = true ? "0.33.3" : "0.0.0-dev";
     MESSAGES = {
       en: {
         installer: {

package/dist/installer-gui.js

@@ -1067,7 +1067,7 @@ async function oauthLogin(opts) {
 }
 
 // installer/installer-gui.ts
-var VERSION = true ? "0.33.1" : "0.0.0-dev";
+var VERSION = true ? "0.33.3" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.33.1",
+  "version": "0.33.3",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",