Tools reference

The HeyAlbert MCP server has five read-only tools (search_people, get_dossier, recent_signals, draft_outreach, meeting_brief) plus search and fetch for ChatGPT; each returns JSON with a source on every fact.

Last updated October 25, 2026

All tools are read-only. Person ids are opaque tokens returned by search; pass them to the dossier, draft and brief tools. Every fact carries its source URL and estimates are labeled. Credit costs apply to Agents & API credit accounts; seats use the daily limits in limits & errors.

Credit cost by tool

search_people

Find people in HeyAlbert. Every filter is optional and filters combine with AND. Returns id, name, title, company, city, state, metro, wealth band (estimate), confidence grade, whether a dossier exists, and why the person matched.

Credit cost: 0.1 credit per result returned.

Example response, trimmed. Rohan Mahalingam and the companies named are fictional, as in our sample report.

{
  "results": [
    {"id": "EXAMPLE_ID", "name": "Rohan Mahalingam", "title": "Operating Partner",
     "company": "Greyfield Lane Ventures", "city": "Austin", "state": "TX",
     "band": "$25M+ likely", "grade": "A", "has_dossier": true,
     "why_matched": "metro Austin; role founder; recent SEC filings"}
  ],
  "returned": 1, "total_matches": 1,
  "usage": {"rows_used_today": 1, "rows_cap": 250},
  "note": "Bands are estimates. Open a person with get_dossier(id) for cited facts."
}

get_dossier

The full cited profile: headline, summary, wealth band with its basis, values with their sources and estimate flags, wealth origin, work and companies, city of residence, adult family, education, philanthropy, boards, India ties, likely causes (estimate), political signal or "No public signal", SEC filings, social links, news mentions, open questions and sources.

Credit cost: 1 credit. Counts as one dossier open.

Example response, trimmed. Rohan Mahalingam and the companies named are fictional, as in our sample report.

{
  "id": "EXAMPLE_ID", "name": "Rohan Mahalingam",
  "headline": "Co-founder and former CEO, Quillmere Systems",
  "wealth": {"band": "$25M+ likely", "is_estimate": true,
             "basis": "Disclosed $310M sale of Quillmere Systems (2023)",
             "sources": ["<acquirer 8-K URL>"]},
  "residence": {"city": "Austin", "state": "TX"},
  "philanthropy": [{"fact": "Chairs a family foundation focused on STEM education",
                    "source": "<IRS Form 990-PF URL>"}],
  "political_signal": "No public signal",
  "sources": ["..."]
}

recent_signals

“Why now” events already in HeyAlbert’s data, with no live scraping: high-confidence news mentions, SEC filings (Forms 3, 4 and 5, 13D/G, 144, D), nonprofit and 990 updates, political gifts and property changes. Each row has the person, event, date and source URL.

Credit cost: Included (no credits).

Example response, trimmed. Rohan Mahalingam and the companies named are fictional, as in our sample report.

{
  "signals": [
    {"date": "2024-06-12", "signal_type": "sec",
     "person": {"id": "EXAMPLE_ID", "name": "Rohan Mahalingam", "company": "Northfield Peak Technologies"},
     "event": "Form 4: sale of acquirer shares", "source_url": "<SEC filing URL>"}
  ],
  "returned": 1, "total_in_window": 1, "days": 120
}

draft_outreach

A short personalized intro email built only from cited facts in the person’s dossier. Returns subject, body, the facts used with sources, a warm-path line only when a real shared affiliation is found in cited facts, and for RIAs a list of compliance flags. HeyAlbert never sends the email.

Credit cost: 1 credit for the dossier + 0.5 credit for the draft.

Example response, trimmed. Rohan Mahalingam and the companies named are fictional, as in our sample report.

{
  "subject": "Fellow UT Austin alum",
  "body": "Hi Rohan, congratulations on the STEM scholarships ...",
  "facts_used": [{"fact": "Foundation funded STEM scholarships (2024)", "source": "<URL>"}],
  "warm_path": "Shared alma mater: UT Austin (cited on his side)",
  "compliance_flags": []
}

meeting_brief

A one-page prep brief: snapshot, talking points, recent news, philanthropy, adult family, wealth context (an estimate, for preparation only), political signal and open questions, every point cited. Includes a ready-to-read brief_markdown.

Credit cost: 1 credit for the dossier + 0.5 credit for the brief.

Example response, trimmed. Rohan Mahalingam and the companies named are fictional, as in our sample report.

{
  "brief_markdown": "# Rohan Mahalingam\n**Snapshot:** Operating Partner, Greyfield Lane Ventures; Austin, TX ...",
  "talking_points": [{"point": "Quillmere Systems sale (2023)", "source": "<URL>"}],
  "open_questions": ["..."]
}

search and fetch

The pair that ChatGPT connectors and deep research expect. search(query) reads a short plain-English query, such as “physicians in Dallas $25M+”, into the same filters as search_people. fetch(id) returns the cited dossier for one result.

Credit cost: search, 0.1 credit per result returned; fetch, 1 credit.