@leadbay/mcp 0.33.2 → 0.33.4

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog — @leadbay/mcp
 
+## 0.33.4 — 2026-09-02
+
+`leadbay_enrich_contacts` moves from `granularWriteTools` to
+`compositeWriteTools` (product#4050).
+
+It is the only tool that enriches ONE chosen person — `leadId` + `contactId`,
+paid-candidate path first, org-contact path on `NOT_FOUND` — but it sat behind
+`LEADBAY_MCP_ADVANCED=1`, which hosted never sets. No granular tool has been
+called from a hosted IP in 30 days. The daily check-in prompt and the pull-leads
+NEXT STEPS table already told the agent to call it, so on hosted they named a
+tool that was not registered. `zoe+dogfood@leadbay.ai`'s scheduled agent
+reached for `leadbay_pin_contact` instead (41 `contact not found` over 12 days;
+see 0.33.3). Same registration pattern as add/remove/pin/unpin/update_contact
+and set_lead_status: granular-shaped, lives in `tools/`, default write surface,
+still hidden by `LEADBAY_MCP_WRITE=0`. Not in `COMPOSITE_FILE_TOOL_NAMES`, so
+`_triggered_by` stays optional.
+
+What moved with it, so the tool works on the surface it now lands on:
+
+- **The result hint names a read that exists there.** It said "re-check
+  `leadbay_get_contacts`", which is advanced-only. It now says re-read the
+  lead's contacts via `leadbay_research_lead_by_id` (or `get_contacts` where
+  exposed).
+- **The description carries routing.** `routing` + `rendering_hint`
+  frontmatter, added to `TOOLS_WITH_ROUTING`; the `prefer_when` states that a
+  `source:"paid"` candidate id from `research_lead_by_id` is valid input and
+  that pinning does not enrich anyone. Cross-routes to `enrich_titles`
+  (by title, many leads), `pin_contact`, `prepare_outreach`.
+- **The pin/unpin 404 hint and `heuristics/pinnable-contacts` name it** as the
+  direct route alongside `enrich_titles` and `add_contact`. `enrich_titles`'s
+  WHEN NOT TO USE drops the "(granular)" label.
+
+Tests: `packages/mcp/test/enrich-contacts-default-surface.test.ts` drives the
+real MCP `tools/list` — present with `includeWrite:true, includeAdvanced:false`,
+absent with `includeWrite:false`, and every `leadbay_*` the description and
+the call hint name is itself registered on that surface.
+`packages/core/test/unit/tools/pin-contact-hint-names-enrich-contacts.test.ts`
+pins the hint.
+
+## 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/README.md

@@ -634,7 +634,7 @@ Use `dry_run: true` to validate domain formatting and wizard reachability withou
 
 - Tokens live only in your MCP client's config file — they never traverse the network except to `api-{region}.leadbay.app`.
 - The `leadbay_login` tool from the OpenClaw adapter is **not** registered on MCP: exposing a credential-taking tool to an LLM is a prompt-injection risk. Use the token path above.
-- The `leadbay_add_note` tool is a write action flagged `optional: true`. If your client supports per-tool opt-in, leave it disabled until you need it. `leadbay_enrich_contacts` is a granular tool exposed only when `LEADBAY_MCP_ADVANCED=1`.
+- The `leadbay_add_note` tool is a write action flagged `optional: true`. If your client supports per-tool opt-in, leave it disabled until you need it. `leadbay_enrich_contacts` (enrich one named contact) is on the default write surface since 0.33.4; it was advanced-only before.
 
 ### Privacy & telemetry
 

package/dist/bin.js

@@ -2282,15 +2282,41 @@ WHEN NOT TO USE: as a default \u2014 answering with even a free-text reason give
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
-    leadbay_enrich_contacts = `Order email and/or phone enrichment for a specific contact. Tries the paid-contact path and falls back to the org-contact path on NOT_FOUND. Each email reveal and each phone reveal consumes QUOTA. Both \`email\` and \`phone\` default to \`true\` \u2014 a bare call enriches both channels.
+    leadbay_enrich_contacts = `## WHEN TO USE
 
-WHEN TO USE: when you have a specific \`contact_id\` (from leadbay_get_contacts) and want to enrich just that one.
+Trigger phrases: "enrich this contact", "get this person's email", "find <name>'s phone number", "reveal the email of <name> at <company>", "enrich the managing director, not the president", "enrichir le DG \xE0 la place du pr\xE9sident".
 
-WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow.
+Do NOT use for: "enrich the CEOs / a job title across my leads" \u2192 \`leadbay_enrich_titles\`; "pin / mark this person as the priority contact" \u2192 \`leadbay_pin_contact\`; "draft an email / prepare outreach for this lead" \u2192 \`leadbay_prepare_outreach\`.
+
+Prefer when: the user names ONE person on ONE company \u2014 pass the lead id + that contact's own id. A \`source:"paid"\` candidate id from leadbay_research_lead_by_id is valid input. Pinning does not enrich anyone.
+
+Examples that SHOULD invoke this tool:
+- "Get me Jane Doe's email at Acme."
+- "Enrich the managing director at Cromology, not the president."
+- "Reveal the phone number for this contact."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Enrich the CEOs across my top 10 leads."
+- "Pin Jane Doe as the main contact on Acme."
+- "Draft an outreach email for Acme."
+
+## RENDER (quick)
+
+One line: "Enrichment started for <name> (<email / phone>)". Then re-read the
+lead's contacts every ~30s via leadbay_research_lead_by_id and report when
+the requested channel has landed. Never print a credits figure.
+
+---
+
+Order email and/or phone enrichment for a specific contact. Tries the paid-contact path and falls back to the org-contact path on NOT_FOUND. Each email reveal and each phone reveal consumes QUOTA. Both \`email\` and \`phone\` default to \`true\` \u2014 a bare call enriches both channels.
+
+WHEN TO USE: when the user has already picked WHO they want on a company and you hold that person's \`contact_id\` \u2014 from \`leadbay_research_lead_by_id\` (\`reachable\` / \`candidates\` lists) or \`leadbay_get_contacts\` where exposed. A \`source: "paid"\` candidate id is the normal input here: it is the person Leadbay suggested but has not resolved yet, and this tool is what resolves them. What to expect on the re-read depends on which id you passed. **Paid candidate:** the candidate row never carries email or phone; when the provider finds a channel, the person appears as a \`source: "org"\` row (new, or merged into an existing org contact for the same person) with a DIFFERENT id, and that row holds the channel and is pinnable. If nothing is found, the candidate row reads \`enrichment_done: true\` with no channel and no org row is created. **Org contact** (\`source: "org"\`, e.g. adding phone to someone who already has an email): the SAME row is updated in place, same id.
+
+WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow. Not to mark someone as the priority contact \u2014 that is leadbay_pin_contact, and pinning does not enrich anyone.
 
 ## QUOTA, NOT CREDITS
 
-Enrichment is gated by QUOTA (the per-window allowance in \`leadbay_account_status\`), not a credit balance. **Never pre-refuse because a credit number looks low or zero** \u2014 a freemium/fresh account with quota left can enrich even when its credit counter reads 0. The reveal either fits the remaining quota or the backend returns 429 (\`quota_exceeded\`); only THEN surface the exhausted window + wait-or-top-up choice. The \`credits_remaining\` field on the result is **advisory internal context only \u2014 do NOT display it**. Because it can read \`0\` on an account that still has quota, printing \`_(N credits remaining)_\` would falsely tell the user they're out. Do not render a credits balance at all; if the user asks where they stand, call \`leadbay_account_status\` and show the quota gauge instead. The actual per-contact cost (\`enrichment.credits_used\`) appears on the contact via leadbay_get_contacts after enrichment.
+Enrichment is gated by QUOTA (the per-window allowance in \`leadbay_account_status\`), not a credit balance. **Never pre-refuse because a credit number looks low or zero** \u2014 a freemium/fresh account with quota left can enrich even when its credit counter reads 0. The reveal either fits the remaining quota or the backend returns 429 (\`quota_exceeded\`); only THEN surface the exhausted window + wait-or-top-up choice. The \`credits_remaining\` field on the result is **advisory internal context only \u2014 do NOT display it**. Because it can read \`0\` on an account that still has quota, printing \`_(N credits remaining)_\` would falsely tell the user they're out. Do not render a credits balance at all; if the user asks where they stand, call \`leadbay_account_status\` and show the quota gauge instead. The actual per-contact cost (\`enrichment.credits_used\`) appears on the contact after enrichment.
 
 **Channels: when the user asks to enrich a contact without naming a channel, confirm scope via \`ask_user_input_v0\`** \u2014 \`"Enrich email only, or email + phone? (phone uses more quota)"\` \u2192 \`["Email only", "Email + phone"]\` \u2014 then pass the chosen \`email\`/\`phone\` flags. Skip the question only if they already said which channel(s) they want.
 
@@ -2300,7 +2326,7 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 
 WHEN TO USE: as the agent's go-to enrichment entry point, immediately before proposing outreach.
 
-WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular). Speculatively, before the user has committed to outreaching \u2014 enrichment consumes quota. **NOT to add "titles" or "LinkedIn" to a list** \u2014 a contact's \`job_title\` and \`linkedin_page\` already ride on the contact record; they are FREE and need no enrichment. If the user asks for "title and LinkedIn only", read those fields directly (e.g. leadbay_get_contacts / leadbay_research_lead_by_id); do NOT launch a job here. This tool is strictly the email / phone reveal, which consumes quota.
+WHEN NOT TO USE: to enrich a single named contact \u2014 that's leadbay_enrich_contacts. Speculatively, before the user has committed to outreaching \u2014 enrichment consumes quota. **NOT to add "titles" or "LinkedIn" to a list** \u2014 a contact's \`job_title\` and \`linkedin_page\` already ride on the contact record; they are FREE and need no enrichment. If the user asks for "title and LinkedIn only", read those fields directly (e.g. leadbay_get_contacts / leadbay_research_lead_by_id); do NOT launch a job here. This tool is strictly the email / phone reveal, which consumes quota.
 
 ## ENRICHMENT CONSUMES QUOTA \u2014 the model to reason with
 
@@ -3688,7 +3714,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 +3736,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_contacts\` with the lead id + this candidate's id enriches exactly this person. \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) does the same by job title. When the provider finds an email or phone, each writes a NEW org contact for that person (or merges into an existing one). It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row. If nothing was found, no org contact exists and there is nothing to pin.
+- 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. "Enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_contacts\` with that person's id (or \`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 +5698,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 +5721,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_contacts\` with the lead id + this candidate's id enriches exactly this person. \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) does the same by job title. When the provider finds an email or phone, each writes a NEW org contact for that person (or merges into an existing one). It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row. If nothing was found, no org contact exists and there is nothing to pin.
+- 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. "Enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_contacts\` with that person's id (or \`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 +6144,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 +6239,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 +6251,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 +6317,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) => ({
@@ -6558,7 +6632,7 @@ var init_enrich_contacts = __esm({
           email_requested: email,
           phone_requested: phone,
           credits_remaining: creditsRemaining,
-          hint: "Enrichment started (runs async). Re-check leadbay_get_contacts every ~30s and treat the contact as done only when the REQUESTED channel actually landed \u2014 " + [email ? "`email` present" : null, phone ? "`phone_number` present" : null].filter(Boolean).join(" AND ") + " (contact.enrichment.done alone is NOT enough: a contact previously enriched for the other channel already shows done:true, so a phone reveal can be reported before phone_number arrives). Then report the result \u2014 don't end your turn leaving it for the user to reprompt. Bound the wait: if the requested field hasn't landed after ~90s\u20132min of spaced re-checks, it likely can't be resolved \u2014 report that plainly (naming the channel that didn't resolve) rather than polling forever. EXCEPTION: if the user explicitly asked NOT to wait (background/'I'll check later'), don't run this loop \u2014 hand back the leadId + contactId and tell them to ask again / re-check later."
+          hint: "Enrichment started (runs async). Re-read the lead's contacts every ~30s (leadbay_research_lead_by_id; or leadbay_get_contacts where exposed) and treat the contact as done only when the REQUESTED channel actually landed \u2014 " + [email ? "`email` present" : null, phone ? "`phone_number` present" : null].filter(Boolean).join(" AND ") + " \u2014 on the person's row: for a `source:\"paid\"` candidate that is a NEW `source:\"org\"` row with a different id (the candidate row itself never carries a channel and only flips enrichment_done; done with no org row means nothing was found), for a `source:\"org\"` contact it is the same row (contact.enrichment.done alone is NOT enough: a contact previously enriched for the other channel already shows done:true, so a phone reveal can be reported before phone_number arrives). Then report the result \u2014 don't end your turn leaving it for the user to reprompt. Bound the wait: if the requested field hasn't landed after ~90s\u20132min of spaced re-checks, it likely can't be resolved \u2014 report that plainly (naming the channel that didn't resolve) rather than polling forever. EXCEPTION: if the user explicitly asked NOT to wait (background/'I'll check later'), don't run this loop \u2014 hand back the leadId + contactId and tell them to ask again / re-check later."
         };
       }
     };
@@ -11785,11 +11859,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 directly with leadbay_enrich_contacts (the lead id + this contact id), enrich by job title with leadbay_enrich_titles, or add them with leadbay_add_contact \u2014 each produces a NEW org contact with a different id, which is pinnable. Note that pinning does not decide who gets enriched: leadbay_enrich_titles selects people by job title, leadbay_enrich_contacts by the contact id you pass.';
     pinContact = {
       name: "leadbay_pin_contact",
       description: leadbay_pin_contact,
@@ -11813,7 +11888,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 +11907,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 +11931,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 +14053,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 +14066,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 +14279,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 +14404,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 = [
@@ -21846,7 +21942,6 @@ var init_dist = __esm({
     ];
     granularWriteTools = [
       qualifyLead,
-      enrichContacts,
       addNote,
       selectLeads,
       deselectLeads,
@@ -21998,6 +22093,12 @@ var init_dist = __esm({
       pinContact,
       unpinContact,
       updateContact,
+      // enrichContacts is granular-shaped (one POST per contact) but registered
+      // HERE, not in granularWriteTools: it is the only tool that enriches ONE
+      // chosen person (leadId + contactId) rather than a job title, and hosted
+      // never sets LEADBAY_MCP_ADVANCED, so behind that gate no hosted agent could
+      // act on a person it had already identified (product#4050).
+      enrichContacts,
       // createCustomField is granular-shaped but file-import prompts depend on it
       // to preserve source-system links without requiring advanced-tool exposure.
       createCustomField,
@@ -25625,7 +25726,7 @@ var FRICTION = `Problem reports: when the user asks you to report a Leadbay prob
 var MENTAL_MODEL = `How Leadbay works (mental model): Leadbay is a sales inbox, not a queryable database. Each day the user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently \u2014 some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; the user acting on leads (outreach, skips, saves) does.`;
 var QUOTA_TOPUP = `Quota & top-ups: when a tool returns QUOTA_EXCEEDED / 429, the user has TWO options \u2014 wait for the window reset (daily / weekly / monthly resets shown in leadbay_account_status), OR top up AI credits (top-ups clear the throttle IMMEDIATELY \u2014 they are not subject to the same window). Always offer BOTH options; default-recommending 'wait until tomorrow' is wrong when a 30-second top-up unblocks the same call. If the host exposes leadbay_create_topup_link, OFFER it on every quota wall: 'Want me to generate a top-up link?' \u2014 when the user says yes, call leadbay_create_topup_link and surface the returned Stripe URL as a clickable link for the user to open in their browser. (Sibling leadbay_open_billing_portal is for ongoing subscription changes, not one-shot top-ups.) AFTER the user has topped up: do NOT keep refusing operations. A top-up invalidates every prior 429 and every stale 'you're at your quota' snapshot. The moment the user signals they topped up / bought credits / added credits \u2014 even WITHOUT re-calling account_status \u2014 treat the previous quota state as void and RETRY the originally failed call. (Best practice: re-call leadbay_account_status to surface the fresh state to the user, then retry; but the retry itself does NOT require a successful account_status check first. If the retry hits the wall again, THEN you have evidence the top-up didn't land; only then re-offer top-up / wait.) The agent's job after a top-up is to RESUME the workflow the user was on, not gate-keep.
 
-Show the refreshed quota AFTER a paid action has actually COMPLETED: when leadbay_bulk_enrich_status reports the job done \u2014 all_done, OR a plateau you've decided is terminal (overall_progress.done stopped climbing across spaced polls, so some contacts are unresolvable and all_done stays false) \u2014 OR a top-up the user confirmed landed, call leadbay_account_status once and render the refreshed quota \u2014 the per-window %/$ gauge (Daily/Weekly/Monthly) it returns \u2014 so the user sees where they now stand. Wait for genuine completion: leadbay_enrich_contacts only LAUNCHES an async reveal (it returns a hint to check back in ~60s), so do NOT refresh quota right after it \u2014 the usage isn't reflected yet. For that single-contact flow, refresh only once leadbay_get_contacts shows the REQUESTED channel actually landed \u2014 the requested email and/or phone_number present \u2014 NOT enrichment.done alone (that flag is already true for a contact enriched on the other channel earlier, so a phone reveal could otherwise trigger the refresh before phone_number arrives). This is the canonical quota surface; do NOT hand-roll a 'credits' line in its place. Skip it only when account_status reports unlimited_credits, quota_error, or a null quota (nothing to show), or when billing is genuinely unavailable. Do it ONCE per completed action \u2014 not after every poll while work is still in progress.`;
+Show the refreshed quota AFTER a paid action has actually COMPLETED: when leadbay_bulk_enrich_status reports the job done \u2014 all_done, OR a plateau you've decided is terminal (overall_progress.done stopped climbing across spaced polls, so some contacts are unresolvable and all_done stays false) \u2014 OR a top-up the user confirmed landed, call leadbay_account_status once and render the refreshed quota \u2014 the per-window %/$ gauge (Daily/Weekly/Monthly) it returns \u2014 so the user sees where they now stand. Wait for genuine completion: leadbay_enrich_contacts only LAUNCHES an async reveal (it returns a hint to check back in ~60s), so do NOT refresh quota right after it \u2014 the usage isn't reflected yet. For that single-contact flow, refresh only once a re-read of the lead's contacts (leadbay_research_lead_by_id; leadbay_get_contacts where exposed) shows the REQUESTED channel actually landed \u2014 the requested email and/or phone_number present \u2014 NOT enrichment.done alone (that flag is already true for a contact enriched on the other channel earlier, so a phone reveal could otherwise trigger the refresh before phone_number arrives). This is the canonical quota surface; do NOT hand-roll a 'credits' line in its place. Skip it only when account_status reports unlimited_credits, quota_error, or a null quota (nothing to show), or when billing is genuinely unavailable. Do it ONCE per completed action \u2014 not after every poll while work is still in progress.`;
 var TRANSIENT_401 = `Transient 401s (DO NOT narrate as an auth problem): Leadbay bearer tokens do NOT expire on a timer, and the client already auto-retried this call once before surfacing it. So a lone AUTH_EXPIRED / 401 from a tool is almost always a brief Leadbay-side hiccup, NOT a sign the user must sign in again. When you see ONE, just silently retry the operation once more and carry on \u2014 do NOT tell the user to log in again, reconnect the connector, reauthorize, or 're-load Leadbay', and do NOT surface the bare '401' to them at all. Only if calls keep failing across several attempts should you mention it \u2014 and then frame it as a possible Leadbay-side issue or a possible logout (you cannot tell which from here), and offer to report it to the team. Never turn a one-off 401 into a 'your connection needs re-authenticating' message; that is the wrong read on a connection that is actually working.`;
 var TRIGGERED_BY = `Trigger provenance (MANDATORY): every Leadbay composite-tool call MUST carry a non-empty \`_triggered_by\` argument \u2014 the verbatim slice of the user's most recent message that this call is acting upon. Quote literally; do NOT paraphrase, summarize, or substitute a one-word label like "leads" or "request" (those are rejected). If you are acting WITHOUT a fresh user message (a memory recall, a scheduled run, a self-initiated retry), pass the actual instruction you are acting on \u2014 the recalled directive, the schedule's intent, or the original request being retried \u2014 so the value is always a real, auditable trace. Strip any secrets the user pasted (API keys, passwords, card numbers, full home addresses) \u2014 replace with [REDACTED]. A composite call missing or blanking this field is rejected with LAST_PROMPT_REQUIRED; just re-call with the field set. This is a protocol requirement on EVERY composite invocation (not just the first), independent of any telemetry setting.`;
 var VERIFICATION = `After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.`;
@@ -27901,7 +28002,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.33.2";
+var VERSION = "0.33.4";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -4873,15 +4873,41 @@ WHEN NOT TO USE: as a default \u2014 answering with even a free-text reason give
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
-var leadbay_enrich_contacts = `Order email and/or phone enrichment for a specific contact. Tries the paid-contact path and falls back to the org-contact path on NOT_FOUND. Each email reveal and each phone reveal consumes QUOTA. Both \`email\` and \`phone\` default to \`true\` \u2014 a bare call enriches both channels.
+var leadbay_enrich_contacts = `## WHEN TO USE
 
-WHEN TO USE: when you have a specific \`contact_id\` (from leadbay_get_contacts) and want to enrich just that one.
+Trigger phrases: "enrich this contact", "get this person's email", "find <name>'s phone number", "reveal the email of <name> at <company>", "enrich the managing director, not the president", "enrichir le DG \xE0 la place du pr\xE9sident".
 
-WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow.
+Do NOT use for: "enrich the CEOs / a job title across my leads" \u2192 \`leadbay_enrich_titles\`; "pin / mark this person as the priority contact" \u2192 \`leadbay_pin_contact\`; "draft an email / prepare outreach for this lead" \u2192 \`leadbay_prepare_outreach\`.
+
+Prefer when: the user names ONE person on ONE company \u2014 pass the lead id + that contact's own id. A \`source:"paid"\` candidate id from leadbay_research_lead_by_id is valid input. Pinning does not enrich anyone.
+
+Examples that SHOULD invoke this tool:
+- "Get me Jane Doe's email at Acme."
+- "Enrich the managing director at Cromology, not the president."
+- "Reveal the phone number for this contact."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Enrich the CEOs across my top 10 leads."
+- "Pin Jane Doe as the main contact on Acme."
+- "Draft an outreach email for Acme."
+
+## RENDER (quick)
+
+One line: "Enrichment started for <name> (<email / phone>)". Then re-read the
+lead's contacts every ~30s via leadbay_research_lead_by_id and report when
+the requested channel has landed. Never print a credits figure.
+
+---
+
+Order email and/or phone enrichment for a specific contact. Tries the paid-contact path and falls back to the org-contact path on NOT_FOUND. Each email reveal and each phone reveal consumes QUOTA. Both \`email\` and \`phone\` default to \`true\` \u2014 a bare call enriches both channels.
+
+WHEN TO USE: when the user has already picked WHO they want on a company and you hold that person's \`contact_id\` \u2014 from \`leadbay_research_lead_by_id\` (\`reachable\` / \`candidates\` lists) or \`leadbay_get_contacts\` where exposed. A \`source: "paid"\` candidate id is the normal input here: it is the person Leadbay suggested but has not resolved yet, and this tool is what resolves them. What to expect on the re-read depends on which id you passed. **Paid candidate:** the candidate row never carries email or phone; when the provider finds a channel, the person appears as a \`source: "org"\` row (new, or merged into an existing org contact for the same person) with a DIFFERENT id, and that row holds the channel and is pinnable. If nothing is found, the candidate row reads \`enrichment_done: true\` with no channel and no org row is created. **Org contact** (\`source: "org"\`, e.g. adding phone to someone who already has an email): the SAME row is updated in place, same id.
+
+WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow. Not to mark someone as the priority contact \u2014 that is leadbay_pin_contact, and pinning does not enrich anyone.
 
 ## QUOTA, NOT CREDITS
 
-Enrichment is gated by QUOTA (the per-window allowance in \`leadbay_account_status\`), not a credit balance. **Never pre-refuse because a credit number looks low or zero** \u2014 a freemium/fresh account with quota left can enrich even when its credit counter reads 0. The reveal either fits the remaining quota or the backend returns 429 (\`quota_exceeded\`); only THEN surface the exhausted window + wait-or-top-up choice. The \`credits_remaining\` field on the result is **advisory internal context only \u2014 do NOT display it**. Because it can read \`0\` on an account that still has quota, printing \`_(N credits remaining)_\` would falsely tell the user they're out. Do not render a credits balance at all; if the user asks where they stand, call \`leadbay_account_status\` and show the quota gauge instead. The actual per-contact cost (\`enrichment.credits_used\`) appears on the contact via leadbay_get_contacts after enrichment.
+Enrichment is gated by QUOTA (the per-window allowance in \`leadbay_account_status\`), not a credit balance. **Never pre-refuse because a credit number looks low or zero** \u2014 a freemium/fresh account with quota left can enrich even when its credit counter reads 0. The reveal either fits the remaining quota or the backend returns 429 (\`quota_exceeded\`); only THEN surface the exhausted window + wait-or-top-up choice. The \`credits_remaining\` field on the result is **advisory internal context only \u2014 do NOT display it**. Because it can read \`0\` on an account that still has quota, printing \`_(N credits remaining)_\` would falsely tell the user they're out. Do not render a credits balance at all; if the user asks where they stand, call \`leadbay_account_status\` and show the quota gauge instead. The actual per-contact cost (\`enrichment.credits_used\`) appears on the contact after enrichment.
 
 **Channels: when the user asks to enrich a contact without naming a channel, confirm scope via \`ask_user_input_v0\`** \u2014 \`"Enrich email only, or email + phone? (phone uses more quota)"\` \u2192 \`["Email only", "Email + phone"]\` \u2014 then pass the chosen \`email\`/\`phone\` flags. Skip the question only if they already said which channel(s) they want.
 
@@ -4891,7 +4917,7 @@ var leadbay_enrich_titles = `Order contact enrichments by job title across many
 
 WHEN TO USE: as the agent's go-to enrichment entry point, immediately before proposing outreach.
 
-WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular). Speculatively, before the user has committed to outreaching \u2014 enrichment consumes quota. **NOT to add "titles" or "LinkedIn" to a list** \u2014 a contact's \`job_title\` and \`linkedin_page\` already ride on the contact record; they are FREE and need no enrichment. If the user asks for "title and LinkedIn only", read those fields directly (e.g. leadbay_get_contacts / leadbay_research_lead_by_id); do NOT launch a job here. This tool is strictly the email / phone reveal, which consumes quota.
+WHEN NOT TO USE: to enrich a single named contact \u2014 that's leadbay_enrich_contacts. Speculatively, before the user has committed to outreaching \u2014 enrichment consumes quota. **NOT to add "titles" or "LinkedIn" to a list** \u2014 a contact's \`job_title\` and \`linkedin_page\` already ride on the contact record; they are FREE and need no enrichment. If the user asks for "title and LinkedIn only", read those fields directly (e.g. leadbay_get_contacts / leadbay_research_lead_by_id); do NOT launch a job here. This tool is strictly the email / phone reveal, which consumes quota.
 
 ## ENRICHMENT CONSUMES QUOTA \u2014 the model to reason with
 
@@ -6279,7 +6305,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 +6327,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_contacts\` with the lead id + this candidate's id enriches exactly this person. \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) does the same by job title. When the provider finds an email or phone, each writes a NEW org contact for that person (or merges into an existing one). It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row. If nothing was found, no org contact exists and there is nothing to pin.
+- 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. "Enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_contacts\` with that person's id (or \`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 +8289,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 +8312,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_contacts\` with the lead id + this candidate's id enriches exactly this person. \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach\` with \`enrich: true\`) does the same by job title. When the provider finds an email or phone, each writes a NEW org contact for that person (or merges into an existing one). It has a **different \`id\`** from the paid candidate, so re-read the contacts list afterwards and pin the \`source: "org"\` row. If nothing was found, no org contact exists and there is nothing to pin.
+- 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. "Enrich the Directeur G\xE9n\xE9ral rather than the Pr\xE9sident" is \`leadbay_enrich_contacts\` with that person's id (or \`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 +8706,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 +8794,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 +8806,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 +8872,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) => ({
@@ -9078,7 +9152,7 @@ var enrichContacts = {
       email_requested: email,
       phone_requested: phone,
       credits_remaining: creditsRemaining,
-      hint: "Enrichment started (runs async). Re-check leadbay_get_contacts every ~30s and treat the contact as done only when the REQUESTED channel actually landed \u2014 " + [email ? "`email` present" : null, phone ? "`phone_number` present" : null].filter(Boolean).join(" AND ") + " (contact.enrichment.done alone is NOT enough: a contact previously enriched for the other channel already shows done:true, so a phone reveal can be reported before phone_number arrives). Then report the result \u2014 don't end your turn leaving it for the user to reprompt. Bound the wait: if the requested field hasn't landed after ~90s\u20132min of spaced re-checks, it likely can't be resolved \u2014 report that plainly (naming the channel that didn't resolve) rather than polling forever. EXCEPTION: if the user explicitly asked NOT to wait (background/'I'll check later'), don't run this loop \u2014 hand back the leadId + contactId and tell them to ask again / re-check later."
+      hint: "Enrichment started (runs async). Re-read the lead's contacts every ~30s (leadbay_research_lead_by_id; or leadbay_get_contacts where exposed) and treat the contact as done only when the REQUESTED channel actually landed \u2014 " + [email ? "`email` present" : null, phone ? "`phone_number` present" : null].filter(Boolean).join(" AND ") + " \u2014 on the person's row: for a `source:\"paid\"` candidate that is a NEW `source:\"org\"` row with a different id (the candidate row itself never carries a channel and only flips enrichment_done; done with no org row means nothing was found), for a `source:\"org\"` contact it is the same row (contact.enrichment.done alone is NOT enough: a contact previously enriched for the other channel already shows done:true, so a phone reveal can be reported before phone_number arrives). Then report the result \u2014 don't end your turn leaving it for the user to reprompt. Bound the wait: if the requested field hasn't landed after ~90s\u20132min of spaced re-checks, it likely can't be resolved \u2014 report that plainly (naming the channel that didn't resolve) rather than polling forever. EXCEPTION: if the user explicitly asked NOT to wait (background/'I'll check later'), don't run this loop \u2014 hand back the leadId + contactId and tell them to ask again / re-check later."
     };
   }
 };
@@ -13931,6 +14005,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 directly with leadbay_enrich_contacts (the lead id + this contact id), enrich by job title with leadbay_enrich_titles, or add them with leadbay_add_contact \u2014 each produces a NEW org contact with a different id, which is pinnable. Note that pinning does not decide who gets enriched: leadbay_enrich_titles selects people by job title, leadbay_enrich_contacts by the contact id you pass.';
 var pinContact = {
   name: "leadbay_pin_contact",
   description: leadbay_pin_contact,
@@ -13954,7 +14029,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 +14064,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 +16064,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 +16077,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 +16284,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 +16409,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 = [
@@ -22762,7 +22857,6 @@ var granularReadTools = [
 ];
 var granularWriteTools = [
   qualifyLead,
-  enrichContacts,
   addNote,
   selectLeads,
   deselectLeads,
@@ -22914,6 +23008,12 @@ var compositeWriteTools = [
   pinContact,
   unpinContact,
   updateContact,
+  // enrichContacts is granular-shaped (one POST per contact) but registered
+  // HERE, not in granularWriteTools: it is the only tool that enriches ONE
+  // chosen person (leadId + contactId) rather than a job title, and hosted
+  // never sets LEADBAY_MCP_ADVANCED, so behind that gate no hosted agent could
+  // act on a person it had already identified (product#4050).
+  enrichContacts,
   // createCustomField is granular-shaped but file-import prompts depend on it
   // to preserve source-system links without requiring advanced-tool exposure.
   createCustomField,
@@ -23647,7 +23747,7 @@ var FRICTION = `Problem reports: when the user asks you to report a Leadbay prob
 var MENTAL_MODEL = `How Leadbay works (mental model): Leadbay is a sales inbox, not a queryable database. Each day the user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently \u2014 some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; the user acting on leads (outreach, skips, saves) does.`;
 var QUOTA_TOPUP = `Quota & top-ups: when a tool returns QUOTA_EXCEEDED / 429, the user has TWO options \u2014 wait for the window reset (daily / weekly / monthly resets shown in leadbay_account_status), OR top up AI credits (top-ups clear the throttle IMMEDIATELY \u2014 they are not subject to the same window). Always offer BOTH options; default-recommending 'wait until tomorrow' is wrong when a 30-second top-up unblocks the same call. If the host exposes leadbay_create_topup_link, OFFER it on every quota wall: 'Want me to generate a top-up link?' \u2014 when the user says yes, call leadbay_create_topup_link and surface the returned Stripe URL as a clickable link for the user to open in their browser. (Sibling leadbay_open_billing_portal is for ongoing subscription changes, not one-shot top-ups.) AFTER the user has topped up: do NOT keep refusing operations. A top-up invalidates every prior 429 and every stale 'you're at your quota' snapshot. The moment the user signals they topped up / bought credits / added credits \u2014 even WITHOUT re-calling account_status \u2014 treat the previous quota state as void and RETRY the originally failed call. (Best practice: re-call leadbay_account_status to surface the fresh state to the user, then retry; but the retry itself does NOT require a successful account_status check first. If the retry hits the wall again, THEN you have evidence the top-up didn't land; only then re-offer top-up / wait.) The agent's job after a top-up is to RESUME the workflow the user was on, not gate-keep.
 
-Show the refreshed quota AFTER a paid action has actually COMPLETED: when leadbay_bulk_enrich_status reports the job done \u2014 all_done, OR a plateau you've decided is terminal (overall_progress.done stopped climbing across spaced polls, so some contacts are unresolvable and all_done stays false) \u2014 OR a top-up the user confirmed landed, call leadbay_account_status once and render the refreshed quota \u2014 the per-window %/$ gauge (Daily/Weekly/Monthly) it returns \u2014 so the user sees where they now stand. Wait for genuine completion: leadbay_enrich_contacts only LAUNCHES an async reveal (it returns a hint to check back in ~60s), so do NOT refresh quota right after it \u2014 the usage isn't reflected yet. For that single-contact flow, refresh only once leadbay_get_contacts shows the REQUESTED channel actually landed \u2014 the requested email and/or phone_number present \u2014 NOT enrichment.done alone (that flag is already true for a contact enriched on the other channel earlier, so a phone reveal could otherwise trigger the refresh before phone_number arrives). This is the canonical quota surface; do NOT hand-roll a 'credits' line in its place. Skip it only when account_status reports unlimited_credits, quota_error, or a null quota (nothing to show), or when billing is genuinely unavailable. Do it ONCE per completed action \u2014 not after every poll while work is still in progress.`;
+Show the refreshed quota AFTER a paid action has actually COMPLETED: when leadbay_bulk_enrich_status reports the job done \u2014 all_done, OR a plateau you've decided is terminal (overall_progress.done stopped climbing across spaced polls, so some contacts are unresolvable and all_done stays false) \u2014 OR a top-up the user confirmed landed, call leadbay_account_status once and render the refreshed quota \u2014 the per-window %/$ gauge (Daily/Weekly/Monthly) it returns \u2014 so the user sees where they now stand. Wait for genuine completion: leadbay_enrich_contacts only LAUNCHES an async reveal (it returns a hint to check back in ~60s), so do NOT refresh quota right after it \u2014 the usage isn't reflected yet. For that single-contact flow, refresh only once a re-read of the lead's contacts (leadbay_research_lead_by_id; leadbay_get_contacts where exposed) shows the REQUESTED channel actually landed \u2014 the requested email and/or phone_number present \u2014 NOT enrichment.done alone (that flag is already true for a contact enriched on the other channel earlier, so a phone reveal could otherwise trigger the refresh before phone_number arrives). This is the canonical quota surface; do NOT hand-roll a 'credits' line in its place. Skip it only when account_status reports unlimited_credits, quota_error, or a null quota (nothing to show), or when billing is genuinely unavailable. Do it ONCE per completed action \u2014 not after every poll while work is still in progress.`;
 var TRANSIENT_401 = `Transient 401s (DO NOT narrate as an auth problem): Leadbay bearer tokens do NOT expire on a timer, and the client already auto-retried this call once before surfacing it. So a lone AUTH_EXPIRED / 401 from a tool is almost always a brief Leadbay-side hiccup, NOT a sign the user must sign in again. When you see ONE, just silently retry the operation once more and carry on \u2014 do NOT tell the user to log in again, reconnect the connector, reauthorize, or 're-load Leadbay', and do NOT surface the bare '401' to them at all. Only if calls keep failing across several attempts should you mention it \u2014 and then frame it as a possible Leadbay-side issue or a possible logout (you cannot tell which from here), and offer to report it to the team. Never turn a one-off 401 into a 'your connection needs re-authenticating' message; that is the wrong read on a connection that is actually working.`;
 var TRIGGERED_BY = `Trigger provenance (MANDATORY): every Leadbay composite-tool call MUST carry a non-empty \`_triggered_by\` argument \u2014 the verbatim slice of the user's most recent message that this call is acting upon. Quote literally; do NOT paraphrase, summarize, or substitute a one-word label like "leads" or "request" (those are rejected). If you are acting WITHOUT a fresh user message (a memory recall, a scheduled run, a self-initiated retry), pass the actual instruction you are acting on \u2014 the recalled directive, the schedule's intent, or the original request being retried \u2014 so the value is always a real, auditable trace. Strip any secrets the user pasted (API keys, passwords, card numbers, full home addresses) \u2014 replace with [REDACTED]. A composite call missing or blanking this field is rejected with LAST_PROMPT_REQUIRED; just re-call with the field set. This is a protocol requirement on EVERY composite invocation (not just the first), independent of any telemetry setting.`;
 var VERIFICATION = `After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.`;
@@ -24668,7 +24768,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.4" : "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.4" : "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.4" : "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.4",
   "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",