One call runs one query, returning ~10 matches by default (one page). To go deeper on a single query — "find people in my network matching my ICP" — pass max_results (up to 100): the tool pages through the matches for you, each ~10-profile page counting as one search against the daily budget. To search different people — a list of names, or one filter per company — loop this tool inside a run_code block, one call per name or company (that's breadth; max_results is depth on one query). Searches are paced a few seconds apart and serialized across this user's LinkedIn work, so a deep search or a long loop can take a couple of minutes; tell the user to expect a short wait before a large run. If a search comes back paused or rate-limited, stop and tell the user which searches remain — the account is paused and further calls won't run until it lifts.

Scope filters combine with keywords and can be used alone for a single filtered search:

• connections_of — restrict to the first-degree connections of specific people, passed as their provider_ids (as returned by an earlier search or profile lookup). To work up to a buyer through someone the user just connected with, pass that person in connections_of and the target company in advanced_keywords={'company': 'Acme Corp'} to surface who they know there. network_distance is a separate filter on the user's own degree and combines with this — add [2] to keep just the connections the user isn't already directly linked to.

• advanced_keywords — native LinkedIn keyword sub-filters: a dict with any of first_name, last_name, title, company, school (each a string).

• profile_language — ISO 639-1 codes (e.g. ['en']) that narrow any of the above to profiles written in those languages. A refinement, not a search on its own — pair it with keywords or another filter.

When this runs in an agent, the matches are saved and linked to the workspace Output tab automatically (deduped by profile). Pass list_name (a short slug) to name their list — a discovery search, the people connected to someone, prospects to work through; reuse the same slug across a loop or follow-up searches to gather everything into one list. Absent a slug, matches land in the 'default' list. Outside an agent, results are returned only.

Returns up to max_results matching profiles with provider_id, name, headline, network_distance, location, and profile_url. Each match's headline is the member's own tagline: often their current role and company (e.g. to see which companies 2nd-degree matches work at), but frequently a title alone, so a headline that omits a company is not evidence they work elsewhere. total_count is LinkedIn's full match count for the query when it returns one, but LinkedIn now omits it on most Classic searches (so it's often null): only say "showing N of ~M" when it's a number exceeding the profiles returned, and never invent a total. Use has_more — True when more results exist beyond those returned — to decide whether to offer to pull more. Present the results to the user so they can pick the right person. An error about being "heavily queued" is transient pacing back-pressure — retry shortly rather than reporting it as not found.

That field list is the whole of it — a search result carries no connection count, follower count, or employment history. Present what comes back as it is; a search the user wanted to look at is finished at that point. When the ask genuinely needs one of the missing fields — a connection-count threshold, employment history to personalize from — pass the matches' profile URLs to enrich_linkedin_profiles, which returns them for the whole list in one paid call (connections_count is the field a connection-count filter reads) and spends no LinkedIn account budget. When the decision also turns on whether the user is already connected to them, use setup_linkedin_sequence(action_type='resolve') instead; connection status is the one thing enrichment cannot answer.

Rate-limited — shares one daily LinkedIn search budget with all other LinkedIn people searches. On success, a dict {'success': True, 'profiles': [...], 'total_count': int | None, 'has_more': bool, 'searches_remaining_today': int}. profiles holds up to max_results matches; total_count is the query's full match count when LinkedIn returns one (often null since its Aug-2026 Classic Search change), so lean on has_more for whether more results exist; and searches_remaining_today is the post-search budget, so you can size a follow-up loop without re-checking. In an agent, also saved_to_list (the list the matches were saved to) and saved_count; outside an agent, a passed list_name yields a null saved_to_list with a persist_note. If the account tripped its pause partway through paging, the (still valid) partial results come back with paused: True and a note — surface it: further searches won't run until the pause lifts.

On a failed search: {'success': False, 'profiles': [], 'error': ..., 'searches_remaining_today': int}. On a pre-flight refusal (daily limit reached or account paused), searches_remaining_today is omitted: {'success': False, 'error': ...}.