LinkedIn warm-lead discovery: list leads, find emails, and draft outreach from your AI tools.
Scored across 15 tools
Most tools target distinct resources and actions (sources, warm leads, templates, outreach). A few source-management tools overlap slightly—add_source can also set a schedule and preview_source vs run_source_once are adjacent concepts—but the detailed descriptions clearly delineate each.
Nearly every tool follows a consistent snake_case verb_noun pattern (add_source, remove_source, list_warm_leads, get_warm_lead_detail, save_template, set_source_schedule). The lone exception, ping, is a well-understood convention and does not break the pattern.
15 tools for a multi-domain server (source lifecycle, lead management, templates, paid outreach) is well-scoped, with each tool covering a meaningful operation and no obvious redundancy.
Source lifecycle (add/remove/schedule/run/cancel/preview), lead retrieval (list/detail/best-of-run/export/find_email), and templates (list/save) are well covered. Minor gaps exist—no update/delete for templates and no direct message-send tool (deferred to the app)—but core workflows are complete.
Attach the right person to a Hiring lead that has none, or whose job poster is a recruiter (can_add_person in list_hiring_leads). first_name is required; last_name, job_title, linkedin_profile_url (https://www.linkedin.com/in/...) and email are optional. A contact you already have with the same LinkedIn profile is linked, not copied. One added person per lead; excluded people are refused. A message already drafted without a person stays; the next draft_message for the lead writes to the added person. Free to call. REQUIRES confirm:true to act; without it returns a dry-run.
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| confirm | No | ||
| job_title | No | ||
| last_name | No | ||
| first_name | Yes | ||
| hiring_lead_id | Yes | ||
| linkedin_profile_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false/destructiveHint=true, yet the description adds substantial context: one added person per lead, excluded people refused, dedup-by-LinkedIn linking instead of copying, the effect on already-drafted messages, and the confirm/dry-run contract. This is well beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the opening clause and every sentence carries a distinct fact (format, dedup, cardinality, draft interaction, cost, confirm). It is dense and slightly packed, but there is little waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the definition covers eligibility, required vs optional inputs, dedup behavior, side effects on drafting, cost, and the dry-run/confirm gate. An agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must carry the burden and largely does: it marks first_name required, lists last_name/job_title/linkedin_profile_url/email as optional, gives the LinkedIn URL format, and explains confirm. Only hiring_lead_id is left implicit (inferred from 'Attach...to a Hiring lead').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Attach the right person to a Hiring lead') and pins the scope to leads that have none or whose poster is a recruiter. It references sibling tools (list_hiring_leads, draft_message), so an agent can place it precisely without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit eligibility gate ('that has none, or whose job poster is a recruiter (can_add_person in list_hiring_leads)') and a hard precondition (REQUIRES confirm:true, otherwise dry-run). The when-to-use condition is fully specified rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a LinkedIn discovery source. Keyword, competitor/creator, Company page, and Hiring sources accept an optional Daily or Custom schedule; omission keeps today's Daily behavior for new sources and preserves the saved schedule when reactivating. Custom weekdays use ISO numbering (1=Monday through 7=Sunday), and one local_time applies to every selected weekday in the IANA timezone. Starting a source scans now, then it follows its schedule, Daily or Custom alike: by default the last 24 hours (a creator or Company page: its latest post from the last 7 days, skipped at no charge when an earlier scan already covered it), or with lookback_days 7 and max_credits (the backfill credit limit) the last 7 days. Each later scan covers the time since the scan before; after a Custom start the next scan is on the next selected day, not later the same day. If its first scan has to wait (a scan failed in the last day or 3 times in 7 days, a scan is still running, the source's share of today's budget is used, the balance is low or the daily budget funds other sources first), the source still starts and the result says when its first scan runs. Switching an active source's schedule to Daily makes its next scan due now; saving the schedule it already has changes nothing. For source_type=company, profile_url must be a linkedin.com/company/... page and the saved source remains explicitly company. Post sources are saved PAUSED and are Once-only, so they reject schedule: choose post_engagement_scope, optionally preview, then call run_source_once. For source_type=hiring, job_titles is one role: its job title first, then up to two other names companies use for the same role (for a different role, add another Hiring source). With job_country (an ISO country code such as GB, or "anywhere"; required) it finds companies whose LinkedIn job posts are hiring for that role; each lead is one job post, up to 50 leads per run (a 7-day start's max_credits stops at that many leads), and the dry run states the scan fee and lead price. Two Hiring sources are the same when the job title (capitals ignored) and the country match, whatever the other names. Free to call, except that with lookback_days 7 the confirmed call spends up to max_credits now, outside the daily budget. REQUIRES confirm:true to act; without it returns a dry-run. Re-adding a removed source revives its history.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| keyword | No | ||
| post_url | No | ||
| schedule | No | ||
| job_titles | No | Required for hiring: the job title first, then up to two other names for the same role. | |
| job_country | No | Required for hiring: an ISO country code such as GB, or "anywhere". | |
| max_credits | No | With lookback_days 7 only: the backfill credit limit for the 7-day scan, as in run_source_once. Spent now, outside the daily budget. | |
| profile_url | No | Required for competitor_creator (/in/ URL) or company (/company/ URL). | |
| source_type | Yes | ||
| keyword_mode | No | ||
| lookback_days | No | Keyword, competitor/creator, Company page, Hiring: what the first scan covers. 7 = scan the last 7 days now (requires max_credits), then follow the schedule. 1 or omitted = scan the last 24 hours now (a creator or Company page: its latest post), then follow the schedule. | |
| post_engagement_scope | No |
Cancel an in-flight one-time run (run_source_once / catchup_source) for a discovery source. Free, immediate, no confirm needed: it stops paid scanning work; leads already found stay in Warm Leads and unspent credits are refunded automatically. Stopping is not a failure and starts no other scan: when the run is the 7-day scan that started an active source, the source keeps its schedule and its next scan covers only the time since that start. Returns cancelled_runs: 0 means nothing was in flight (the run may have already finished). Does not otherwise touch daily monitoring; use remove_source or the app to change that.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes |
Draft AI outreach messages for warm leads (contact IDs from list_warm_leads). PAID: 3 credits PER MESSAGE, so cost = 3 × number of contact_ids or hiring_lead_ids (each lead gets one AI-drafted message, charged as drafting proceeds; max 5 leads per call). Creates a campaign (or reuses one via campaign_id from a previous call) and returns the drafted text. When every campaign lead is generated and no message job remains open, the campaign becomes ready to review and send in the app; this completion has the same opt-in automatic integration delivery behavior as Generate All. promotion='promoted' means the campaign is ready after the check, including repeat or concurrent no-op checks, not necessarily that this call performed the status transition. Hiring leads: pass hiring_lead_ids (from list_hiring_leads, max 5) instead of contact_ids; each lead is drafted from its job post to its person, or to its hiring team while it has no person (no name is invented; same price; every per-lead result names it by hiring_lead_id), a second job of the same person is skipped and not charged, and the default template is Hiring LinkedIn DM (written from the job post to who the person is for that job: someone at the hiring company, the person who posted it, or an outside recruiter). Template choice: template_id (see list_templates) OR inline_config (custom template body, tone, language, AI variables), not both; default is the Warm Leads LinkedIn DM template. The Hiring LinkedIn DM works only with hiring_lead_ids. Takes ~10-40s per message. Failed or unresolved generations are NOT auto-refunded (matches the app). Requires a completed Business Profile. Run ONE draft call per campaign at a time: concurrent calls on the same campaign can mis-attribute failures and overwrite each other's template config. Provide a fresh idempotency_key per new batch; reuse the same key ONLY to retry an uncertain call. A reused key returns the previous call's stored result regardless of new arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | No | ||
| contact_ids | No | ||
| template_id | No | ||
| campaign_name | No | ||
| inline_config | No | ||
| hiring_lead_ids | No | Hiring leads to draft, instead of contact_ids. | |
| idempotency_key | Yes |
Export warm leads as structured rows (one row per contact; engagement columns show the most recent engagement). action_person_slot, action_company_slot, action_reason_slot, and action_cell form the current action grid; action_verdict, action_verdict_reason, and action_verdict_skip_category remain as the lossy compatibility view. icp_score/icp_score_reason are the canonical unified score; deprecated icp_qualified_score/qualification_score_reason remain for wire compatibility. Free — costs no credits. YOU write the CSV/file from the returned rows. days filters by discovery date and DEFAULTS TO 2 (set it explicitly for a longer window, max 365). Caps at 5000 rows and sets truncated=true if more exist within the window; use limit to request fewer.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description carries most of the behavioral burden and does so well: zero credit cost, a hard 5000-row cap with a truncated=true flag, the days default of 2 and 365 max, and the fact that the caller must write the output file. It stops short of describing ordering, pagination, or how truncation interacts with limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: the row/column shape comes first, then the schema-drift field groupings, then cost, then the days/cap mechanics. The canonical-vs-deprecated field enumeration is verbose but is genuine information an agent needs to interpret returned columns, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still conveys the return shape (one row per contact, engagement columns, action grid vs. lossy compatibility view, canonical icp_score vs. deprecated fields), plus the truncation flag and row cap. Nothing an agent needs to interpret or bound the result set is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and largely does: `days` is documented as filtering by discovery date with a default of 2 and max 365, and `limit` is documented as requesting fewer rows than the cap. `limit`'s interaction with truncated is only implied, keeping this below 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope: 'Export warm leads as structured rows (one row per contact; engagement columns show the most recent engagement).' The 'YOU write the CSV/file from the returned rows' clause clarifies what the tool does NOT do, implicitly separating it from a file-producing or list-paging sibling, but it never names list_warm_leads or get_warm_lead_detail, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives operational context (free, costs no credits; days defaults to 2, set explicitly for a longer window) which tells an agent how to call it, but never says when to prefer export_leads over list_warm_leads or get_warm_lead_detail. Usage is implied by 'export' vs 'list' rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find work emails for warm leads by contact ID. PAID — 5 credits per contact actually queued; unfound emails are refunded automatically. Max 200 contacts. Async: returns scrape_job_id.
| Name | Required | Description | Default |
|---|---|---|---|
| contact_ids | Yes | ||
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations existing, the description carries substantial extra context the annotations cannot express: it is a paid operation at 5 credits per contact actually queued, unfound emails are refunded, there is a 200-contact cap, and it is asynchronous returning a scrape_job_id. This is exactly the cost/payment/side-effect disclosure an agent needs before invoking a tool flagged destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short clauses, front-loaded with the purpose, then cost, then limit, then async behavior — every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly names the return value (scrape_job_id) and covers cost, refunds, and batch limits. It could be slightly more complete by indicating how to follow up on the async job (e.g., which sibling polls the scrape job), but the essentials for correct invocation are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies contact_ids (warm-lead contacts, and the 200 max matching the schema's maxItems) but says nothing about the required idempotency_key's role or format, leaving half the parameter set undocumented beyond the schema's type constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find work emails') plus the scope ('for warm leads by contact ID'), which no sibling tool offers — none of add_source, list_warm_leads, get_warm_lead_detail, etc. retrieve email addresses. An agent can identify this as the email-enrichment tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'for warm leads by contact ID', which tells the agent the required input category, but there is no explicit when-to-use/when-not statement or named alternative (e.g., versus get_warm_lead_detail when only existing data is needed). It is adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Signado's stored Best of run selections. Each completed run ranks eligible leads by composite score. The top lead is always selected. More leads are selected when their score is 60 or higher, up to five total. This is stored at discovery time, not a live re-ranking. verdict, why, and angle stay in the response as nullable legacy fields from historical model-selected runs; use action_person_slot, action_company_slot, action_reason_slot, action_cell, and action_verdict for current Action guidance. Free — costs no credits. Returns selected warm leads from completed runs, newest run first, with the same lead identity fields as list_warm_leads, current icp_score, the exact run-engagement quote when textual evidence exists, run_id, and run_timestamp. Filter by source_id, canonical run/batch run_id, or a UTC calendar date. Paginate completed run boundaries with limit (default 20, max 50) and offset.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Optional UTC calendar date in YYYY-MM-DD format. | |
| limit | No | Maximum completed run boundaries in this page. | |
| offset | No | Zero-based offset into filtered newest-first runs. | |
| run_id | No | Optional canonical run/batch UUID. | |
| source_id | No | Optional Discovery source UUID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint=true, but the description goes well beyond that: it discloses the cost profile ('Free - costs no credits'), the snapshot-vs-live semantics, the ranking rules that determine what is returned, and which response fields are deprecated legacy versus current. That is meaningful behavioral context an agent cannot get from the annotation alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and selection rule are front-loaded in the first two sentences, and the later filtering/pagination sentence is dense but useful. The legacy-field sentence is somewhat long and could be tightened, but no sentence is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, five-parameter tool with no output schema, the description covers everything an agent needs: what is returned (lead identity fields, icp_score, quote, run_id, run_timestamp), how results are ordered and paginated, and which fields are deprecated. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description largely restates what the schema already documents (date format, run_id, source_id, limit default/max). It does add the framing that limit paginates 'completed run boundaries' and that results are newest-run-first, which clarifies unit-of-pagination beyond the raw property text, but most of the content is redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get Signado's stored Best of run selections') and immediately pins down the exact selection semantics (top lead always, plus any with score >= 60, max five). It distinguishes itself from siblings by referencing list_warm_leads as the source of shared lead-identity fields, so an agent knows this is a stored-picks view rather than the general warm-lead list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the stored snapshot applies ('stored at discovery time, not a live re-ranking') and steers the agent away from legacy fields toward the action_* fields. However, it never names an explicit alternative tool or a when-not condition, so the choice versus list_warm_leads is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete newest-first LinkedIn engagement history and current action grid for one warm lead. The action_person_slot, action_company_slot, action_reason_slot, and action_cell fields are current; action_verdict fields remain as the lossy compatibility view. Free — costs no credits. Obtain the contact_id from list_warm_leads.
| Name | Required | Description | Default |
|---|---|---|---|
| contact_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring safety, the description adds genuinely non-obvious behavior: results are ordered newest-first, which fields are current (action_*_slot, action_cell) versus a 'lossy compatibility view' (action_verdict), and that the call consumes no credits. The one soft spot is that 'lossy compatibility view' is asserted without explaining the tradeoff, but the freshness distinction is valuable context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, then field semantics, then cost and ID provenance. Every sentence carries information, though the middle sentence is dense with internal field names that make it harder to scan. Efficient overall with minor density cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must characterize the return, and it does: engagement history plus an action grid, with a note on which fields are current. Cost and ID provenance round it out for a single-parameter read-only tool. It stops short of describing volume, pagination, or what happens for an unknown contact_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single contact_id parameter, so the description must carry meaning and it partially does by stating where to obtain the ID (list_warm_leads). It does not restate the UUID format, though the schema already encodes format/pattern. Baseline 3 is appropriate: it adds provenance but not format or edge-case guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Get) and resource (warm lead detail), then scopes it precisely: 'complete newest-first LinkedIn engagement history and current action grid for one warm lead.' It also implicitly distinguishes itself from the sibling list_warm_leads by operating on 'one warm lead.' An agent can tell these apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit prerequisite/route: 'Obtain the contact_id from list_warm_leads,' which tells the agent to call the sibling first. It also flags the cost model ('Free — costs no credits'), a real usage consideration when choosing among tools. It does not state when NOT to use this tool, keeping it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Hiring leads: companies whose LinkedIn job posts are hiring for the roles in your Hiring sources, newest first. Free: costs no credits. Each lead is one job post with the company, the job (title, place, dates, repost, applicants, apply link), the match score and its reason, the poster, and the person to contact (contact_id works with find_email). When can_add_person is true there is no right person yet: open find_person_url and attach someone with add_hiring_lead_person. Draft messages with draft_message hiring_lead_ids; a lead with no person is drafted to its hiring team. Each lead names its Hiring source (source_id and source_label, the job title and country); filter with source_id. Paginate with limit (default 50, max 200) and offset; when has_more is true, pass next_offset.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| source_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint, but the description adds substantial behavior: 'Free: costs no credits', the full shape of each returned lead, the can_add_person branch, the fallback that a person-less lead is drafted to its hiring team, and pagination semantics via has_more/next_offset. This goes well beyond what the annotation declares.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and free of filler, but it is one long run-on block where pagination, field enumeration, and workflow branching are packed together. Dense rather than wasteful, yet a little more structure would aid scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe return values, and it enumerates them thoroughly (company, job title/place/dates/repost/applicants/apply link, match score and reason, poster, contact). Combined with the pagination and workflow notes, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden and does so: limit default 50 / max 200, offset, next_offset behavior, and source_id as a filter. It even closes the loop by explaining that each lead exposes its own source_id, so the agent knows where the filter value comes from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) plus the resource (Hiring leads) and defines exactly what a lead is: 'companies whose LinkedIn job posts are hiring for the roles in your Hiring sources, newest first.' That scope and ordering immediately distinguish it from list_warm_leads and export_leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear working context by naming the downstream tools and the conditions that route to them (find_email for contacts, add_hiring_lead_person when can_add_person is true, draft_message for outreach). It does not explicitly contrast this list with list_warm_leads, so an agent still has to infer the Hiring-vs-Warm distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the message templates available to this workspace: system presets (the Warm Leads LinkedIn DM default, and the Hiring LinkedIn DM default for hiring_lead_ids, which only Hiring leads can use) plus your own saved templates, with each template body, tone, language and AI variables. Also returns the authoring constraints (allowed tones, languages, variable max-lengths, static variables like {FirstName}, preset AI variables, and your plan's AI-variable limit) for building a save_template or draft_message inline_config. Free, read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
List paid warm leads discovered from LinkedIn engagement, ordered by the stable legacy Action compatibility order (Looking to buy through Skip, then Not assessed), followed by discovery date, score, latest engagement, and contact ID tie-breakers. Free — costs no credits. Paginate with limit (default 50, max 200) and offset (default 0); when has_more is true, pass next_offset as the next offset. Optional discovered_after and discovered_before are exclusive ISO 8601 bounds and compose with pagination. Returns page count, authoritative filtered total_count, has_more, next_offset, and light lead rows with one full primary engagement, aggregate engagement count/latest time, compact source summaries, company fields, canonical icp_score/icp_score_reason, and a best_of_run boolean. The current action grid uses action_person_slot, action_company_slot, action_reason_slot, and action_cell; action_verdict, action_verdict_reason, and action_verdict_skip_category remain as the lossy compatibility view. Best of run is a separate stored per-run composite-score selection. Each offset page is a separate statement snapshot; active discovery can shift rows between pages, so exact-once traversal requires a stable lead set. Excluded receipt rows never appear. Deprecated icp_qualified_score/qualification_score_reason fields remain for wire compatibility. Use get_warm_lead_detail for one contact's complete engagement history.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum leads in this page. | |
| offset | No | Zero-based offset into the filtered legacy-Action-ordered result. | |
| discovered_after | No | Exclusive PostgreSQL-compatible ISO 8601 lower bound for discovered_at. | |
| discovered_before | No | Exclusive PostgreSQL-compatible ISO 8601 upper bound for discovered_at. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint, yet the description discloses cost (free), pagination protocol (has_more/next_offset), snapshot semantics ('each offset page is a separate statement snapshot; active discovery can shift rows'), exclusion of receipt rows, and deprecated wire-compatibility fields. This is unusually rich behavioral disclosure beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and there is little filler, but the single dense paragraph buries the practical pagination guidance under extensive return-shape and field-compatibility detail (action_* slots, deprecated icp fields) that an agent does not need to select or invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full return-value burden and does so thoroughly: page count, total_count, has_more, next_offset, lead row contents, ordering, filtering bounds, and snapshot caveats are all covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit/offset/bounds are already documented in the schema. The description mostly restates defaults and bounds but does add that the date bounds are exclusive and 'compose with pagination,' which is marginal value over the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list paid warm leads from LinkedIn engagement) plus the exact ordering contract, and explicitly names the sibling it is not (get_warm_lead_detail). An agent can distinguish it from the detail and export siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Routes the agent explicitly to get_warm_lead_detail for a single contact's full history and notes the tool is free (no credits), which is real selection context. It lacks a broader when-to-use framing versus list-style siblings, but the alternative routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free connectivity check. Echoes the message back with the server timestamp. Costs no credits and touches no data.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, yet the description adds genuinely new behavioral facts: zero credit cost and no data mutation ('touches no data'), plus what the response contains. It stops short of discussing rate limits or error behavior, so 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with zero filler; the most decision-relevant fact (it is a free, side-effect-free check) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden and discharges it by describing the echoed message plus timestamp. Nothing an agent needs to call this trivial tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single parameter is undocumented in the schema, but the description explains its role by saying the message is echoed back. That is adequate for a one-param echo tool, though it adds nothing about format or length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource purpose ('connectivity check' that 'echoes the message back with the server timestamp'), which is unambiguous. It also cleanly distinguishes itself from all siblings, which are lead-sourcing/template tools, by being a pure connectivity probe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use it: a check that 'costs no credits and touches no data', which tells an agent this is the cheap way to verify a live connection. It does not spell out when-not to use it or name alternatives, but for a trivial ping no alternatives exist, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an optional live preview of a keyword, competitor_creator, Company page, Hiring, or paused post source. Hiring previews list up to 5 recent job posts for the source's titles and country, not scored yet. Company pages use the creator-equivalent 1-credit preview infrastructure while remaining source_type=company. Post previews check public commenters and reactor presence without fetching separate post metadata. A successful empty post preview means no public engagement was found; the post may be quiet, restricted, or unavailable, and the fixed 1-credit charge is retained. Confirmed pre-acceptance failures are refunded; uncertain starts stay charged and pending reconciliation. Takes ~10-60s. Provide a fresh idempotency_key per new preview; reuse it only to retry an uncertain call.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes | ||
| source_type | Yes | ||
| idempotency_key | Yes |
Remove (archive) a discovery source by its exact source ID — stops its scheduled LinkedIn scraping. Free. DESTRUCTIVE for monitoring: queued scrape jobs are cancelled. Historical warm leads keep their source label, and re-adding the same keyword, creator, Company page, or post source later revives it with its history.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, it discloses that queued scrape jobs are cancelled, that historical warm leads retain their source label, and that re-adding the same source revives the history. It also states cost is zero — exactly the kind of side-effect and reversibility context an agent needs before a destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the action and effect front-loaded, then consequences, then reversal semantics. No filler and no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description covers cost, destruction scope, retained history, and reversibility. An agent has everything needed to decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate; it does add the meaningful 'exact source ID' matching nuance. However, it gives no hint of the UUID format or where the ID comes from, leaving most parameter meaning to the schema's pattern and format fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (remove/archive) and resource (discovery source) plus the effect (stops scheduled LinkedIn scraping). Reading it alongside cancel_source_run and add_source, an agent can immediately tell this removes the source itself rather than a single run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the right context (permanent removal of scheduled scraping vs. cancelling a run) and notes cost ('Free.'), but never names the alternative tool for a one-off cancellation. Clear usage context, yet the when-to-use-this-instead routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The preferred verb to run a discovery source ONCE (an active or paused keyword, creator, Company page, or Hiring source, or a paused Once-only post source) without starting Daily monitoring or touching its schedule. lookback_days selects 24 hours or 7 days for keyword, creator, Company page, and Hiring sources; post scans its fixed stored URL. Post scope controls commenters, reactors, or both; Both requires two lead slots and uses a fixed allocation. Requires confirm:true plus max_credits, the backfill credit limit (the most this scan may spend); a Hiring run finds up to 50 leads, so its max_credits stops at that many leads (the dry run states the number). Stage-2 charges/refunds normal wallet credits; a zero-engagement post completes with a net lead charge of 0. Results stream into Warm Leads within minutes. Cancel with cancel_source_run.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| source_id | Yes | ||
| max_credits | No | The backfill credit limit: the most this one-time scan may spend, outside the daily budget. Required with confirm:true. | |
| lookback_days | No | Keyword/creator/Company page/Hiring only; fixed post scans ignore this field. |
Save a reusable message template for this workspace (visible in the app's campaign wizard and via list_templates; usable in draft_message by template_id). Free. Provide the template body — static variables like {FirstName} and AI variables like {{icebreaker}} — plus tone, language and per-AI-variable instructions. Each AI variable may explicitly set source_target to all, post, or lead_comment. Check list_templates first for allowed tones/languages/max-lengths and your plan's AI-variable limit (enforced at draft time, not save time). System templates cannot be modified.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| tone | No | casual_direct | |
| language | No | en-US | |
| template | Yes | ||
| variables | No | ||
| guidelines | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate that it writes. It adds useful context (free, system templates protected, AI-variable limit enforced at draft time not save time), but it never explains the destructive behavior the annotation implies — e.g., what happens on a name collision or whether an existing template is overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and then packs prerequisite checks and constraints into a single efficient paragraph. Every sentence carries operational value; no filler, though the density makes it slightly more than minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with 0% schema description coverage and no output schema, the description does a decent job, but gaps remain: two parameters (guidelines, description) are unexplained, the name-collision/overwrite behavior is undefined, and it defers max-length details entirely to list_templates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the full burden. It explains template body syntax ({FirstName}, {{icebreaker}}), tone, language, per-AI-variable instructions, and source_target values, covering five of seven parameters. It leaves `guidelines` and `description` unmentioned and never clarifies `name` explicitly, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Save a reusable message template for this workspace') and distinguishes itself from siblings by naming list_templates and draft_message as the places where the template surfaces. An agent can tell exactly what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear prerequisites ('Check list_templates first for allowed tones/languages/max-lengths') and a constraint ('System templates cannot be modified'), plus a cost note ('Free'). It does not explicitly state when-not to use it versus an alternative, but the guidance is otherwise concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a Daily or Custom schedule for an existing keyword, competitor/creator, Company page, or Hiring discovery source by UUID or exact name (a Hiring source's name is its label, e.g. "SEO manager · United Kingdom"). Custom weekdays use ISO numbering (1=Monday through 7=Sunday), and the one local_time applies to every selected weekday in the IANA timezone. Post sources are Once-only and reject schedules. Switching an active source to Daily makes its next scan due now (a keyword, creator or Company page scan covers the last 24 hours, a Hiring scan the time since its last scan), then it runs daily; a Custom schedule takes effect at its next selected day and time; saving the schedule a source already has changes nothing. Free to call, but changing recurrence controls future credit-spending runs. REQUIRES confirm:true to act; without it returns a no-write plan.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| schedule | Yes | ||
| source_id | No | ||
| source_name | No |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
draft_message2 fields changedInput schema / properties / template_id / formatRemoved value: -"uuid"Input schema / properties / template_id / patternPrevious value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"add_source1 field changedInput schema / properties / max_credits / descriptionPrevious value: -"With lookback_days 7 only: the one-time credit ceiling for the 7-day scan, as in run_source_once. Spent now, outside the daily budget."New value: +"With lookback_days 7 only: the backfill credit limit for the 7-day scan, as in run_source_once. Spent now, outside the daily budget."run_source_once1 field changedInput schema / properties / max_credits / descriptionAdded value: +"The backfill credit limit: the most this one-time scan may spend, outside the daily budget. Required with confirm:true."add_source1 field changedInput schema / properties / job_titles / descriptionPrevious value: -"Required for hiring: 1-3 job titles to search job posts for."New value: +"Required for hiring: the job title first, then up to two other names for the same role."list_hiring_leads1 field changedInput schema / properties / include_dismissedRemoved value: -{
- "default": false,
- "type": "boolean"
-}add_source2 fields changedInput schema / properties / lookback_daysAdded value: +{
+ "anyOf": [
+ {
+ "const": 1,
+ "type": "number"
+ },
+ {
+ "const": 7,
+ "type": "number"
+ }
+ ],
+ "description": "Keyword, competitor/creator, Company page, Hiring: what the first scan covers. 7 = scan the last 7 days now (requires max_credits), then follow the schedule. 1 or omitted = scan the last 24 hours now (a creator or Company page: its latest post), then follow the schedule."
+}Input schema / properties / max_creditsAdded value: +{
+ "description": "With lookback_days 7 only: the one-time credit ceiling for the 7-day scan, as in run_source_once. Spent now, outside the daily budget.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}add_hiring_lead_personadd_source3 fields changedInput schema / properties / job_countryAdded value: +{
+ "description": "Required for hiring: an ISO country code such as GB, or \"anywhere\".",
+ "maxLength": 20,
+ "minLength": 2,
+ "type": "string"
+}Input schema / properties / job_titlesAdded value: +{
+ "description": "Required for hiring: 1-3 job titles to search job posts for.",
+ "items": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 3,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / source_type / enumPrevious value: -[
- "keyword",
- "competitor_creator",
- "company",
- "post"
-]New value: +[
+ "keyword",
+ "competitor_creator",
+ "company",
+ "post",
+ "hiring"
+]draft_message2 fields changedInput schema / properties / hiring_lead_idsAdded value: +{
+ "description": "Hiring leads to draft, instead of contact_ids.",
+ "items": {
+ "format": "uuid",
+ "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+ "type": "string"
+ },
+ "maxItems": 5,
+ "minItems": 1,
+ "type": "array"
+}Input schema / requiredPrevious value: -[
- "contact_ids",
- "idempotency_key"
-]New value: +[
+ "idempotency_key"
+]list_hiring_leadspreview_source1 field changedInput schema / properties / source_type / enumPrevious value: -[
- "keyword",
- "competitor_creator",
- "company",
- "post"
-]New value: +[
+ "keyword",
+ "competitor_creator",
+ "company",
+ "post",
+ "hiring"
+]run_source_once1 field changedInput schema / properties / lookback_days / descriptionPrevious value: -"Keyword/creator/Company page only; fixed post scans ignore this field."New value: +"Keyword/creator/Company page/Hiring only; fixed post scans ignore this field."add_sourcecancel_source_rundraft_messageexport_leadsfind_emailget_best_of_runget_warm_lead_detaillist_templateslist_warm_leadspingpreview_sourceremove_sourcerun_source_oncesave_templateset_source_scheduleRun LinkedIn outreach from your AI chat: find leads, launch campaigns, send, and reply.
Find LinkedIn prospects, draft outreach, and run human-paced campaigns from your AI agent.
AI agent for LinkedIn outreach: finds the right people, writes in your voice, follows up, replies.
LinkedIn AI agents for B2B: leads, inbox, draft replies, campaigns and posts. You approve each send.
Add one secure layer between your agents and this server.
