# Research and enrichment

## When new information arrives

A new email address, confirmed employer, official website, social profile, or user clarification may make a previously ambiguous contact identifiable. Use it to improve relevant missing or stale professional information while completing the user's original task.

1. Search Ray with `search_crm` using the strongest identifier. If a newly supplied identifier is not stored yet, find the intended contact using its known name or refcode and the user's context. Read the matched contact with `get_profile`, including contact endpoints, affiliations, sources, protected fields, and prior checks. If a new identifier matches a different existing contact, resolve that conflict before attaching it or merging records.
2. Save a user-directed contact edit through `save_contact`, or include information from a real exchange in `record_event`. Preserve existing addresses and employment history. Do not manufacture an exchange to create a contact.
3. Identify what the new evidence can answer: which namesake, current employer, official profile, professional background, or usable photo. Limit the research to those useful questions.
4. Inspect published sources, compare their identifying details, and follow verified links to additional sources. A search snippet is a lead; read the underlying page before treating its claims as confirmed.
5. Save supported findings with source URLs and actual observation times, subject to the effective capture policy. Explain uncertainty where it remains.

If a contact edit is only proposed, do not describe its identifier as already saved. A proposed new contact may not yet have a usable contact refcode; hold dependent enrichment until it exists. Research can still produce findings for the user without claiming they were attached.

## An email address as a research lead

An exact email match is strong evidence, but an address can be shared, mistyped, or reassigned. A generic mailbox such as `info@...` identifies an organization more readily than a person: save it on the firm, never on a person, through `enrich_profile`'s `addresses` with the page it came from, or through `save_contact` (kind `firm`, `email`) when the user gave it. A firm's own address is how a message reaches a firm where nobody is known. A consumer email provider does not imply employment there.

For a business address, inspect the organization's official website and team pages. Search the person's name with the organization or domain. An exact-address public search can help when appropriate for the task; do not include private message text, deal terms, or other unrelated confidential context in public search queries. A page publishing the same address beside a name is stronger evidence than a similar username elsewhere.

Do not construct a LinkedIn slug or photo URL from the email's local part. Do not infer title, seniority, investment thesis, check size, or location from the domain. Follow an actual link or corroborate the specific claim on a published page.

Example: the user supplies a business email for a contact whose name previously matched several people. Search Ray for the address, read the intended profile, and inspect the business's team page. If that page identifies the person and links a professional profile, use that evidence to resolve the match and pursue missing facts. If it identifies someone else, ask about the conflict instead of changing the contact's identity.

## Establish identity before adding facts

Prefer sources that directly connect the identifier, name, and affiliation: official team pages, personal sites linked by those pages, or profiles cross-linked by the person. First-person professional bios and reputable event or publisher bios can supply further evidence. Several sites repeating the same unsupported bio do not create independent corroboration.

Use at least one meaningful connection beyond a matching name. If two people remain plausible, ask one discriminating question, such as which employer or known profile belongs to the contact. Do not choose a photo by facial similarity to another unverified image.

What Ray already holds is also subject to verification. A generic or disputed bio may contain an incorrect city or job and cause searches to exclude the right person. Broaden the search when that happens. Someone can be an angel investor while having a day job outside finance; absence of an investor title does not rule them out.

A website stored in Ray is context too. It can be an article, a newsletter post, a FAQ, a parent company, or a dead or parked domain. Confirm that the page names the organization before taking anything from it, and save a website only after loading it: a domain, or a home page that answers "not found", is not a website. When the real site is found, add it as the primary website and record the wrong stored domain with `review_profile` item `domain`.

## Record facts at the right level

- `enrich_profile` stores sourced links, pictures, email addresses and phone numbers (`addresses`), and supported professional context. Use `identity_evidence` to explain the concrete match, not just "verified online."
- An email address or phone number found on a page goes in `enrich_profile`'s `addresses`, with the page and the time, so the record says where it came from; it follows the research rule, so under Suggest it waits for approval. `save_contact` records an address as the user's own words: use it only for one the user gave you. An address no page publishes stays empty; `firstname@domain` is a guess, not a fact.
- Keep each claim tied to its supporting page. If a context object shares one source URL, include only fields supported by that source; use separate calls or sourced research content when facts come from different pages.
- A sourced bio or summary says only what its sources say. Do not add a company's sector, a person's background or any other description from your own knowledge, however certain it seems, and do not label a portfolio company from its logo or name; leave the description out when the page gives none. This is the most common error in research summaries, and it gathers where the founder's interests are: a logo-only portfolio becomes "sports" or "edtech" because those are the overlaps being looked for.
- A firm's type (`venture_firm`, `angel_group`, `syndicate`, `family_office`, `corporate_venture`, `accelerator`, `other`) goes in `enrich_profile`'s `context` as `firm_type` when a page establishes it, such as an angel network's own site describing its members, and through `save_contact` when the user states it. A type the user set is protected, and research that disagrees is recorded with `review_profile`.
- A firm's pitch or submission form is a link with platform `submission_form`, taken from the firm's own site. Ray fills in no form; tell the user it exists.
- A firm's main phone line and general inbox from its own contact page go on the firm, through `addresses`. A number a page publishes for one person goes on that person.
- `review_profile` records a confirmed check, missing page, or conflicting finding: on a link, the picture, a context field, or a firm's stored `domain`. It preserves the current value. Cite what the checked page actually establishes; a failed fetch cannot confirm that a person or organization does not exist.
- `save_content` can retain a sourced research summary within authorized scope and capture rules. Do not use it, `save_contact`, or `add_note` as a workaround for research approval or protected fields.
- Distinguish professional facts from private fundraising facts. A public investment thesis is not evidence that the investor is interested in this company. A founder's report belongs to the event or appropriate intelligence record.

Preserve human corrections. Do not silently overwrite them with a scraped value. For an explicit correction, change only what the user requested, retaining unrelated fields and source history.

## Finish each record through MCP

Check the live connection and capture rules before starting an enrichment batch. For each record, read current evidence, research a useful gap, and save the supported result as soon as it is ready. Attach research to the relevant person, firm, deal, or round so another agent can retrieve it. Use profile fields for supported professional facts and sourced `research_summary` content for investment criteria, contact routes, fit assessments, and remaining questions that those fields cannot represent. A firm's stages, cheque size, lead preference and how it takes pitches belong in that summary, not in the firm's bio, where the next agent cannot tell them from a description. Preserve qualifications and claim-to-source attribution. Keep query counters and experiment bookkeeping in the private working log.

Inspect the write's returned status, then read the affected profile or workspace record to verify the intended information, sources, and association were saved. A successful request alone is insufficient. If the response is lost or a retry is needed, read current state before resubmitting; avoid duplicate content and use the current version when revising a summary. A write that went to review is not on the record but is in `get_profile`'s `pending_proposals`: when it is there, the write was received, so do not send it again. A saved draft summary is persisted research; a capture proposal still awaits application. Report those states accurately.

End each record with a verified saved improvement, a verified unchanged result, or an explicit pending/blocked outcome. A useful unresolved identity conflict can itself be persisted with its evidence; it does not justify assigning facts to an uncertain person. If evidence adds nothing useful, say so rather than padding the record. If saving or readback fails, retain the evidence and returned refs, report incomplete persistence, and prioritize recovery over further batch research. Reconcile and apply retained findings after reconnecting before gathering more of the same evidence.

## Freshness, failure, and stopping

Use the time you actually checked the source, with its time zone, read from a clock rather than estimated. Do not copy an old observation time into a fresh check or invent a future check time: Ray refuses an observation more than a few minutes later than now, and a saved observation time cannot be corrected afterwards. If sources disagree, compare their publication dates and specificity; report unresolved conflicts.

After a blocked source, try a materially different credible source. Repeating the same URL or altering guessed identifiers is not new research. Stop when the requested facts are supported, reasonable sources are exhausted, or a user clarification is needed. Say "I couldn't verify this from the sources checked" rather than claiming no public information exists.

Do not rerun unchanged failed searches during every conversation. A new identifier, new relevant source, or explicit request to retry is a reason to revisit them. Read prior checks as fallible research notes, not proof that every possible source was searched.

Research requires browsing or another available research capability; Ray stores findings but does not perform web searches. If those capabilities are absent, retrieve existing evidence and identify the remaining gap. Never imply a search happened when it did not.

## Bound each research pass

Unless the user specifies different limits, start with **eight minutes, six search queries, and ten external source fetch attempts per record**, stopping at the first limit reached. These are initial operating defaults to evaluate, not measured optima or claims about a search provider's quota. Stop earlier when the useful questions are answered. A request for a deeper investigation can override these defaults; a higher-priority session limit or an actual service quota still applies.

Count each query in a batched search separately. Count attempted page, document, image, and enrichment-API fetches, including failed requests and retries. Reading or finding text in an already retrieved result does not consume another fetch unless it actually retrieves the source again. Track paid calls and cost separately when available. Share a firm's already-read sources across its people instead of fetching the same pages for each one; retain the source's original observation time.

Use this loop for each record:

1. Read prior findings and identify the unanswered questions. Record the start time, deadline, query/fetch counts, and any user or service limits in the private working log. Use a real clock or monotonic timer when available; the context's initial timestamp is not a running clock.
2. Before each search or fetch, check the time and counters. Choose the smallest request that could answer an outstanding question. Do not submit a batch larger than the remaining allowance. Use a request timeout no longer than the remaining time when the tool supports one.
3. After the request returns, check the clock again, update the counters, and record what it answered. If a call ran past the deadline, retain its result and launch no further research for that record. Do not claim a hard runtime guarantee when the tool cannot enforce a timeout.
4. After two consecutive searches or source attempts yield neither new evidence nor a useful new lead, stop that line of inquiry. Switch once to a materially different credible source or identifier within the remaining budget. If that also yields nothing useful, leave the question unresolved.
5. When answered or bounded out, finish the record through MCP: save supported findings and useful unresolved questions with sources under capture rules, then verify them by reading the affected records. Keep queries tried, elapsed time if measured, stop reason, returned refs/statuses, and recovery details in the private working log. The research budget limits discovery, not persistence and verification of findings already gathered. Continue to the next authorized record when saving is working; otherwise prioritize recovery and report the blocker.

For long batches, checkpoint the ledger and report progress at least every five completed records or 30 minutes, whichever comes first; honor any more frequent communication requirement. Track total elapsed time and requests too, and obey a user-specified overall budget before starting another record. A checkpoint is not a request for permission to continue already authorized work. On resume, reuse the ledger and carry forward counts for an unfinished pass; do not reset the allowance because of a tool failure, context compaction, or a new agent turn. A genuinely new research pass needs new evidence, an explicit retry request, or a separately scoped investigation.

If the service reports throttling, an exhausted quota, or a retry delay, record it. Retry only when the permitted delay fits the remaining budget and the service allows it; do not issue parallel retries, switch identities, or change providers merely to evade a limit. Continue independent work using evidence already retrieved, and distinguish service exhaustion from an unsuccessful search. Never infer the size or reset time of a quota the tool has not reported.

If no reliable clock is available, enforce the query/fetch limits and label elapsed time unmeasured. Never invent timings. Partial research is a useful result when its scope and open questions are explicit; it is not full verification.

## Evaluate usefulness before scaling enrichment

Start with the decision the founder needs: correct identity, supported fit, a usable contact route, a material uncertainty, or a justified next step. Check official team, investment, and contact pages first; use focused search to recover moved pages or resolve a missing fact. A failed team URL can have a useful replacement on the firm's homepage. Record the failed route and the successful alternative so later passes do not repeat the same dead end.

Treat even an official page at the level of the specific claim. Distinguish a published investment range from a promised check, a general mailbox from a founder submission channel, a stated thesis from evidence of current deployment, and a portfolio overlap from confirmed conflict clearance. An inconsistent title on one page should remain qualified. A new observation timestamp does not make an old article newly published.

For an enrichment evaluation, retain a private baseline and compare approaches on the same records and questions. Include straightforward, ambiguous, failed-source, and randomly selected cases; report the selection and denominators. Track supported matches and claims, useful next steps, unresolved questions, time, calls, cost, and reviewer corrections. Label self-assessment and untested provider options. A high API match likelihood is not verification of every returned fact. Do not extrapolate a deliberately difficult sample to the full list.

Measure the enrichment outcome by useful improvements persisted in Ray and verified through MCP. Track proposals, unchanged records, unresolved identities, and blocked writes separately; local-only findings count as unapplied work. Keep experiment logs private and generalize only repeatable lessons into this guide and the evaluation scenarios. Research questions are not mandatory note keys. Preserve source imports and known deal state; a recommendation is not an authorized outreach action or pipeline update.