Find Person

Find ONE specific person by name — optionally pinned by where they used to work — and get a definitive answer in a single call. The user never needs their LinkedIn id or URL.

CHOOSING BETWEEN discover_prospects AND find_person The deciding question: does the user NAME a specific person, or DESCRIBE a kind of person?

USE find_person when the user names someone (a first and last name), however much else they say about them:

• "Message Jane Doe, she used to be at Acme."

• "Is this the John Smith who was at Acme?"

• "Find Pat Lee at Globex and connect." Returns who they are plus proof (e.g. Acme, 2018-2024). Cost: 1 search plus up to 2 profile reads. Drafts nothing. To write to them afterwards, pass the handle to schedule_dm_to_person.

USE discover_prospects when the user describes a GROUP by role, place or topic and wants connection notes written for whoever is found:

• "Find 5 ML engineers in San Francisco and draft notes to them."

• "Reach out to heads of growth in Austin." Searches by query and location, reads each person's profile AND posts, and drafts a note per person. Cost: 1 search plus 2 reads per person (about 11 actions for 5 people). Nothing sends; drafts land in list_drafts. Use it only when the user wants drafts.

NEITHER (use find_prospects or search_prospects) when the user wants a list to browse, or to check a badge such as #hiring, with no notes wanted.

NEVER use discover_prospects to look up a named person: it cannot filter by name or former employer, it returns strangers, and it spends about 11 actions doing so. NEVER use find_person to build a list: it returns at most 2 people.

AMBIGUOUS: "Find me Acme alumni named Jane." This could mean one specific Jane (find_person) or any number of Janes who used to work at Acme, with notes drafted (discover_prospects). A first name only, or a plural, is a group. DO NOT GUESS: the two cost very different amounts and discover_prospects drafts messages. Ask the user one question before calling either, for example: "Do you mean one specific person (give me their full name), or should I find several people matching this and draft notes to them?" Then call exactly one tool.

If the user gave a full name plus any context, choose find_person without asking. Ask only when the request could fit both.

LinkedIn applies the name and employer filters itself, so a match already satisfied them. The profile is then read (profile only, no posts; at most 2 matches; cached) to show WHEN: proof lists the matching job, e.g. Acme, Software Engineer, 2018-2024, status "past".

Read verdict: confirmed exactly one person matched every filter you gave. Use its handle. ambiguous two or more did. Compare headline and location, or add a filter (company, location, title) and call again. unverified NOBODY matched your filters; these people share only the name. Do not present them as the person asked for. none nobody by that name.

A match is a person who satisfies the filters, not proof they are the one the user means: check headline and location against what the user said.

Cost: 1 search, plus 1 profile read per match when evidence is on (free if cached). evidence=false skips the profile read: the match is still confirmed, with no dates. If the daily budget is spent the matches still come back, without proof, and budget_exhausted is set.

SEVERAL PEOPLE: send people (a list of the same fields, up to 50) instead of name. Up to 3 are answered right here as {"status": "done", "results": [...]}. More than 3 return a job_id at once, keep working in the background at a pace LinkedIn tolerates, and email the user when they pause or finish. Read them with get_job: results appear as they come in, and each confirmed person carries a handle you can use straight away.

Args: name: full name, e.g. "Jane Doe". The last word is the surname. (Or send people.) past_company: a company they USED to work at, e.g. "Acme". company: a company they work at NOW. location: where they are now, e.g. "San Francisco". title: words from their current title, e.g. "Chief Scientist". keywords: a soft hint (e.g. a former city). Narrows the search; proves nothing. evidence: read the profile to show dates (default true). include_history: also return their whole work history (default false).

Returns {"verdict", "matches", "more", "searches", "profiles_opened", "budget_exhausted", "note"}. Each match: handle, name, headline, location, distance, profile_url, and (when read) proof [{company, role, from, to, status}]. Pass handle straight to schedule_dm_to_person, get_linkedin_profile (for posts) or enroll_prospect.

Responses:

200: Successful Response (Success Response) Content-Type: application/json