@leadbay/mcp 0.33.2 → 0.33.3

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # 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).

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).
 `;
@@ -6086,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) => ({
@@ -6177,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: {
@@ -6189,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"],
@@ -6247,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) => ({
@@ -11785,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,
@@ -11813,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" };
       }
     };
@@ -11826,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,
@@ -11849,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" };
       }
     };
@@ -13965,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 : [];
@@ -13977,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_`);
@@ -14189,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" } }
@@ -14314,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 = [
@@ -27901,7 +27971,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.33.2";
+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).
 `;
@@ -8648,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) => ({
@@ -8732,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: {
@@ -8744,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"],
@@ -8802,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) => ({
@@ -13931,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,
@@ -13954,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" };
   }
 };
@@ -13983,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" };
   }
 };
@@ -15977,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 : [];
@@ -15989,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_`);
@@ -16195,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" } }
@@ -16320,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 = [
@@ -24668,7 +24737,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.33.2" : "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.2" : "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.2" : "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.2",
+  "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",