fix(mcp): pinning a suggested contact is answered, not retried (product#4050) - #199
Conversation
…ct#4050)
leadbay_pin_contact failed 43 of its 48 production calls in the 180 days to
2026-09-02. Sentry MCP-3A holds exactly 43 events, so every "contact not found"
in the mcp project is a pin call. 41 belong to one scheduled agent,
zoe+dogfood@leadbay.ai, across 12 days and MCP 0.26.0 through 0.33.2. 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. Pin is its third most used
tool and has never once succeeded.
POST /contacts/{id}/pin resolves through org_contacts only, so a paid candidate
id can never resolve there.
The client's shared 404 hint is "Verify the ID is correct" (client.ts:1048).
On this endpoint that is false: the id is correct, it is the wrong namespace.
An agent reads it 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 naming the org-vs-paid split, saying not to retry, and naming the
tools that make the person pinnable.
Both descriptions carry the same rule via a new shared snippet, with the short
form in prefer_when so it lands in the first 600 chars every host reads. The
snippet also states that pinning does not steer enrichment: enrichment selects
by job title and pinnedBy plays no part. That was the second half of the
agent's mistake.
Separately, pinned was invisible. 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 only read back 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. Paid contacts get
no pinned key rather than a synthetic false, matching PaidContactPayload.
Verified live against FR staging with the built branch: pinned false to true to
false across pin and unpin, paid contacts carrying no pin state throughout.
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.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d1b856c173
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // candidate rather than an org contact. Agents read that hint as "look | ||
| // it up again and retry" and hammer the endpoint (43 of 48 production | ||
| // pin calls in the 180 days to 2026-09-02 were this 404). | ||
| if (e?.code === "NOT_FOUND") throw { ...e, hint: NOT_PINNABLE_HINT }; |
There was a problem hiding this comment.
When contact_id is mistyped, stale, or belongs to a deleted org contact, this endpoint returns the same NOT_FOUND, but this branch replaces the accurate verification hint with one asserting that the ID is correct and directing the agent to enrich or add the person. Because the request carries no source information, the tool cannot distinguish those cases from a paid candidate; preserve both possible causes (while still discouraging blind retries) so agents do not conceal bad IDs or create duplicate contacts.
Useful? React with 👍 / 👎.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Well-scoped fix: replaces the misleading 404 hint on pin/unpin with one that correctly explains the org-vs-paid split and tells the agent not to retry, and threads pinned/pinned_by_ai through the three contact-shaping sites. Verified the generated tool-description text matches the .md.tmpl + shared snippet source, the paid/org asymmetry (no synthetic pinned:false on paid contacts) is handled consistently everywhere, the 404-rewrite is safe (errors are plain objects, not Error instances, so the spread preserves all fields), and new tests are all in new files per convention. One minor coverage gap noted inline; no blocking issues found.
| 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, |
There was a problem hiding this comment.
This shaping site gets the same pinned/pinned_by_ai passthrough as research-lead-by-id.ts and get-contacts.ts, but unlike those two, it has no test coverage here — contact-pin-state-passthrough.test.ts only exercises research_lead_by_id and get_contacts. Since existing test files can't be modified, this needs a new test (or an addition to the new pin-state test file) covering get_lead_profile.
1 participant
leadbay_pin_contactfailed 43 of its 48 production calls in the 180 days to 2026-09-02; SentryMCP-3Aholds exactly 43 events, and 41 belong to one scheduled agent that pins asource:"paid"candidate id, whichPOST /contacts/{id}/pincan never resolve. The client's shared 404 hint says "Verify the ID is correct", which on this endpoint is false and reads to an agent as "retry", so pin and unpin now replace it with one naming the org-vs-paid split and saying not to retry, and both descriptions carry the same rule via a new shared snippet that also states pinning never steered enrichment.Separately,
pinnedandpinned_by_aihave been on the backend'sContactPayloadall along and every MCP shaping site dropped them, so a pin could be written but only inferred fromrecommended; they now pass throughresearch_lead_by_id,get_contactsandget_lead_profile, marked 📌 in both markdown contact lists, with paid contacts deliberately carrying no pin key rather than a syntheticfalse.Verified live against FR staging with the built branch (
pinnedfalse to true to false across pin and unpin);pnpm -r testandpnpm -r typecheckgreen.Not fixed here, and the reason the agent reached for pin at all: on hosted there is still no way to enrich one named person, because
leadbay_enrich_contactssits ingranularWriteToolsbehindLEADBAY_MCP_ADVANCED=1and no granular tool has been called from a hosted IP in 30 days. Filed as leadbay/product#4050.[Claude]: authored on Milan's behalf.