docs(mobile-phone-waterfall): add FAQ for diagnosing inaccurate phone numbers

[george-dilthey]

What changed

Added a new FAQ entry to docs/mobile-phone-waterfall.md: "Some of the phone numbers the waterfall is returning are wrong or outdated — how do I find out which provider is responsible?" The entry explains how to enable Output name of successful provider? to attribute each result to its source, and how to test providers individually (rather than nesting waterfalls) to evaluate accuracy side by side.

Why

Intercom conversation #215475575114740 — an Enterprise customer (UpKeep, Abdullah Mamsa) was getting incorrect phone numbers from the Mobile Phone waterfall (specifically an Upcell-provided number that was outdated by ~10 years). He asked how to improve accuracy and which provider Clay recommends. Fin was not involved — the conversation went directly to a human support agent (Bo Morin).

Bo's answer covered two actionable steps:

1. Enable the provider output option so reps can identify which provider returned a bad number and spot patterns
2. Test providers individually rather than nesting waterfalls so results are attributable per source

The mobile-phone-waterfall.md doc already documents Output name of successful provider? as a setting under "Additional column settings" — but no section or FAQ explained why you'd use it or how it helps debug accuracy issues. A user or Fin reading the doc would see the option described but have no guidance connecting it to the accuracy troubleshooting workflow the support agent walked through.

The existing open PRs on this file (#2029, #2030, #2285, #2297) address plan availability restrictions and run-condition/match-rate FAQs — none cover inaccurate/wrong phone numbers vs. missing phone numbers (fill rate).

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475575114740
• Slack thread (same conversation): https://clay-hq.slack.com/archives/C0BJ9PP2CN8/p1787256997241909
• Verifier sub-agent: PASS — Output name of successful provider? confirmed live for all customers with no feature flag: /workspace/clay-base/apps/frontend/src/components/Waterfall/WaterfallSidebarSections/AdditionalFieldSection.tsx:17 (UI toggle, unconditional), /workspace/clay-base/apps/frontend/src/components/Waterfall/WaterfallSidebar.tsx:508-509 (state wired in, default off, user-togglable), /workspace/clay-base/libs/shared/src/WaterfallGroup.ts:44 (API contract), /workspace/clay-base/apps/api/v3/tables/services/waterfall.service.ts:706-766 (backend creates the field when enabled)

Uncertainties

None. The Output name of successful provider? feature is confirmed PASS by the verifier with file:line evidence, no feature flags, and available to all customers. The "test providers individually" guidance is a general workflow recommendation from the support agent, not a product-behavior claim that requires verification. The specific "default waterfall order is balanced for credit vs. accuracy" phrasing from the support agent's reply was intentionally omitted because the verifier could not confirm this rationale in code — the FAQ instead describes the default waterfall as multi-provider coverage without making an unverifiable optimization claim.

Related observations

• The support agent also mentioned "the basic waterfall Clay ships with is the one to run — it's ordered to balance credit spend against accuracy." This is a product design intent claim that the verifier could not confirm in code. The claim was left out of the doc to avoid asserting unverified product intent. If the product team wants to document the waterfall ordering rationale explicitly, that would be a good addition to this section or the "Optimize for (location)" section.
• Multiple open PRs exist on this file (docs(mobile-phone-waterfall): add run-condition and match-rate FAQs #2029, docs(mobile-phone-waterfall): add run-condition and match-rate FAQs #2030, docs(mobile-phone-waterfall): add plan availability note (Launch+ required) #2285, docs(mobile-phone-waterfall): add plan availability note for trial users #2297). All add content to different sections (plan availability, run-condition FAQs). The change in this PR appends to the end of the FAQs section and does not conflict with any of those PRs' additions.

Closes DOC-2049

[linear-code]

DOC-2049