Skip to main content
Glama

Iridium: LinkedIn MCP Server

by com.iridiumhqmcp
OverviewDiscussionsAdmin

find_prospects

Find Prospects

Find people on LinkedIn and, optionally, verify and write to a few of them — one tool that spends only what the filters you asked for actually cost.

USE THIS as the default for any "find me people who..." request. It searches once, narrows for free on the fields the search already returned, and opens full profiles only for the number you allow, best candidates first.

This is the tool that answers "who actually HAS the #hiring badge / the #opentowork badge". Set hiring or open_to_work and give it max_touches: it orders the bucket by the free signals most likely to carry the badge, opens that many profiles — the only place the badge exists — and tells you which candidates it CONFIRMED. Cost is 1 profile touch per candidate confirmed, except that a full Recruiter seat confirms "open to work" for free at search time. Read confirmed and each candidate's confirmed / badges to see who is verified; the rest of the bucket is unverified and the response says so.

Four phases, and you control where it stops: max_touches=0 (default) search + free narrowing only. No profile is opened, nothing is charged against the daily profile budget. This is a browse. max_touches=N additionally opens up to N full profiles (profile AND posts together, in one pass), best-first, to CONFIRM the badge filters. Already-known people are served from cache for free and never counted against N. want_notes=true additionally drafts a connection note for the confirmed candidates, reusing profiles already read — no extra LinkedIn reads, ever. Nothing sends; drafts land in list_drafts.

"#hiring" and "#opentowork" mean TWO DIFFERENT THINGS on LinkedIn, and which one the user means decides what the search costs:

BADGE the frame on someone's PROFILE (is_hiring / is_open_to_work). It is NOT in any people-search result and NOT in their posts. Seeing it means opening that person's profile — one profile touch each — with a single exception: a full Recruiter seat can filter "open to work" at search time for free. This tool's hiring and open_to_work flags mean the BADGE. POST TEXT the hashtag someone typed into a POST. Free to search, opens nobody's profile, and says nothing about their badge. That is search_posts_by_topic, not this tool — "who POSTED about hiring" is a different question from "who HAS the hiring badge", and they return different people.

Honesty contract, worth relaying to the user: checked is how many profiles this call actually opened, cached how many were reused free, confirmed how many really carry the badge, and count - checked - cached are candidates NOBODY has verified. When the daily budget is spent, the candidate list still comes back with budget_exhausted set — the tool never returns an empty list to mean "out of budget", and never silently stops early.

Args: query: what to search for, e.g. "ML engineer" or "Head of Growth". location: plain-text location, e.g. "San Francisco" or "United States". limit: bucket size to search for (1-100; classic LinkedIn plans return at most 10). company / headline_keywords / exclude_headline_keywords / network_distance: free filters applied to the search results themselves — they cost nothing, so use them freely to cut the list before spending touches. Any-of within a filter, all-of across filters. network_distance: DISTANCE_1 (direct connections), DISTANCE_2, DISTANCE_3. hiring: set this to find people who really have the #hiring profile BADGE (not post text). It is the only way to get that answer: no LinkedIn plan can filter on the badge at search time, so candidates are ORDERED by the free signals that correlate with it and then CONFIRMED by opening profiles — 1 touch per candidate confirmed, on every tier, capped by max_touches. The response marks each confirmed candidate and counts them in confirmed. With max_touches=0 nothing is confirmed and this flag only changes the order. For "who POSTED about hiring" use search_posts_by_topic instead: free, and a different question with different people. open_to_work: set this to find people who really have the #opentowork profile BADGE (not post text). On a full Recruiter seat LinkedIn confirms it at search time for free (its own spotlight, 0 touches, results arrive pre-filtered); on every other plan — Recruiter Lite included — it falls back to order-then-confirm at 1 touch per candidate confirmed, capped by max_touches. The tool picks whichever route this account can actually use, and the response says which candidates are confirmed either way. posted_recently: neither badge nor post text — an ACTIVITY filter ("posted at all in the past 30 days", regardless of what about). Free at search time, Sales Navigator seats only; on other plans the search runs without it and tier_note says so. max_touches: how many profiles this call may open BEFORE answering (0-10, default 0). You wait for these, up to 3. More than 3 runs in the background instead: you get a job_id at once, read the bucket and the confirmations as they arrive with get_job, and the user is emailed when it finishes. background_touches: how many of the best remaining candidates to confirm AFTER the answer is sent (0-10, default 0). You do NOT wait for these and they are NOT confirmed in this response — background.queued says how many are running. Ask again in a moment and they come back already confirmed, at no extra cost, because they land in the same cache. Use this to keep a long list moving without making the user wait: "here are 25 people, the best 8 are being confirmed now". want_notes: draft a connection note per confirmed candidate. Default false.

Responses:

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

Input Schema

NameRequiredDescriptionDefault
limitNo
queryYes
hiringNo
companyNo
locationYes
want_notesNo
max_touchesNo
open_to_workNo
posted_recentlyNo
network_distanceNo
headline_keywordsNo
background_touchesNo
exclude_headline_keywordsNo

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full burden and does so in detail: per-candidate touch cost, free cache reuse, the fact that max_touches>3 returns a job_id and emails the user on completion, background_touches results arriving only on a later call, and the explicit guarantee that budget exhaustion returns a populated list with budget_exhausted set rather than an empty list. It also discloses plan-dependent behavior (full Recruiter seat confirms open-to-work for free; Recruiter Lite falls back to order-then-confirm; posted_recently works only on Sales Navigator with a tier_note otherwise). This is exactly the behavior an agent cannot infer from schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and sectioned: purpose, default-usage claim, phase ladder, badge-vs-post-text distinction, honesty contract, then arguments — an agent can stop reading once it has what it needs. However the badge/cost story is told three or four times over (the 'who HAS the #hiring badge' line, the BADGE vs POST TEXT block, then again inside the hiring and open_to_work arg entries), so several sentences restate prior ones rather than earning new space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, no-annotation, no-output-schema tool with tier-dependent branching, this is close to complete: it names the response fields an agent must read (checked, cached, confirmed, budget_exhausted, tier_note, background.queued) and cross-references get_job and list_drafts, which compensate for the missing output schema. The remaining hole is that the three overlapping prospect-search siblings are never disambiguated, leaving the agent's tool-selection decision only partly closed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and there are 13 parameters, so the description must compensate entirely — and it documents all 13, including ranges/defaults (limit 1-100 with a note that classic plans cap at 10; max_touches 0-10 default 0), filter-combination logic ('any-of within a filter, all-of across filters'), and enum meaning for network_distance (DISTANCE_1 = direct connections). Crucially it also clarifies what a flag does NOT mean (hiring = profile badge, not post text) and what happens to the flag on unsupported plans, which is semantics no schema could carry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb+resource chain ('find people on LinkedIn and, optionally, verify and write to a few of them') and explicitly declares itself the default for 'find me people who...' requests, which is far more than a name restatement. It sharply differentiates from search_posts_by_topic, but says nothing about the two most confusable siblings, search_prospects and discover_prospects, whose names an agent could easily mistake for this one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives unusually explicit when-to-use routing for search_posts_by_topic ('who POSTED about hiring' vs 'who HAS the hiring badge') plus a clear decision ladder over max_touches=0 / N / want_notes and background_touches, framed as cost tradeoffs. The gap is that it offers no exclusion or comparison against search_prospects or discover_prospects, so the agent is told 'use this as default' without being told what those siblings are for or when they'd win.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Iridium: LinkedIn MCP Server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources