LinkedIn warm-lead discovery: list leads, find emails, and draft outreach from your AI tools.
Scored across 18 tools
The tools target clearly distinct objects and actions: sources are added, previewed, run once, scheduled, removed, or cancelled with distinct verbs, while leads, templates, exports, budgets, and drafting are cleanly separated. Although several tools return or involve leads, each has a specific role (paged list, detailed history, export rows, stored best-of-run selection) that the descriptions make unambiguous.
All tool names use snake_case and almost all follow a predictable verb_noun pattern such as add_source, list_warm_leads, set_source_schedule, and save_template. The only minor outlier is the standard connectivity tool `ping`, which does not break the overall convention.
Eighteen tools is slightly above the typical well-scoped range, but the server covers several related domains (sources, warm leads, hiring leads, templates, email lookup, budgets, and diagnostics), so most tools earn their place. The set is broad but not bloated.
Core workflows for source creation, lead listing/detail, drafting, templates, scheduling, and budget control are present, but there is no explicit list/get-sources tool, making it hard to enumerate and manage existing sources without relying on lead responses or the app. `find_email` also returns an async scrape_job_id without any companion job-status/results tool, which creates a notable dead end.
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. A scheduled scan that brings you nobody pays a scan fee of 1 credit (the dry run states every price); Run once and a source's first scan never pay one. 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; for a keyword source, pass the keyword_mode it had (with none, only a removed Authors + commenters or All source comes back, with its audience).
| 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 | Keyword only: all (post authors, commenters and reactors from one budget; refused while it is not open to your workspace), post_engagers (commenters and reactors together, from one budget, while that is open to your workspace, otherwise commenters; post_engagement_scope commenters or reactors narrows it), post_authors, or both (Authors + commenters: post authors and their commenters; an All source given both becomes Authors + commenters). When omitted: the mode of the keyword's active source when it has one in another mode; otherwise a new source is all while All is open to your workspace and both when it is not, and an existing source keeps its audience. | |
| 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 | Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters, reactors or both (commenters and reactors together, from one budget); omitted keeps the saved choice. A new keyword (post_engagers), competitor_creator or company source without it takes both while that is open to your workspace, otherwise commenters. Reactors and both on these sources are refused while they are not open to your workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich context beyond annotations: confirm:true is required to act, otherwise a dry-run is returned; 7-day backfills spend max_credits immediately outside the daily budget; scheduled scans can incur a 1-credit scan fee; first scans may be delayed. These details are consistent with destructiveHint=true and materially inform safe use.
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 description is front-loaded with purpose, but it becomes a very long single paragraph dense with edge cases. The content is mostly relevant, yet bullets or sections would make it easier to parse and scan.
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 12-parameter mutation with no output schema, the description covers scheduling semantics, credit behavior, confirm/dry-run behavior, source-type differences, delayed first scans, and revival behavior. No critical decision point appears 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 58%, but the description compensates for most gaps by explaining schedule modes, keyword_mode defaults, lookback_days with max_credits, job_titles/job_country, profile_url constraints, and post_engagement_scope. It adds little for keyword and post_url, which remain largely schema-defined, so it is not fully exhaustive.
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?
Opens with a specific verb and resource: "Add a LinkedIn discovery source." It then enumerates source types and their distinct behaviors, letting an agent distinguish this from siblings like preview_source and run_source_once.
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 explicit when-to-use guidance, including that post sources are saved PAUSED and should use post_engagement_scope, optionally preview, then run_source_once. It also covers schedule choices, hiring requirements, and re-adding removed sources with the correct keyword_mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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; a run stopped before it picks its leads charges nothing; leads already delivered stay in Warm Leads, and nothing more is charged. 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=true; the description goes far beyond, disclosing billing behavior (a run stopped before picking leads charges nothing, delivered leads stay in Warm Leads), that stopping is not a failure and starts no other scan, schedule/coverage semantics for the 7-day scan, and the meaning of the cancelled_runs return value.
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 first clause and each following sentence carries distinct, non-redundant information (cost, confirmation, return value, alternatives). It is dense for a single paragraph, but no sentence is 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?
There is no output schema, and the description compensates by explaining what cancelled_runs means, so the agent knows how to interpret the result. Combined with the destructive annotation and the rich side-effect/cost context, nothing needed to call this 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 schema only supplies format/pattern, not meaning. The description implies source_id identifies the discovery source whose run is cancelled, which is the essential semantic, but it adds no detail about the identifier beyond that inference.
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 precise verb+resource ('Cancel an in-flight one-time run') and scopes it to the two run-creating siblings (run_source_once / catchup_source) for a discovery source. This lets an agent distinguish it from remove_source and run_source_once 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?
Explicitly states when to use it (cancelling an in-flight one-time run, free and immediate, no confirm), when it is irrelevant ('Returns cancelled_runs: 0 means nothing was in flight'), and names the alternative for the adjacent need ('Does not otherwise touch daily monitoring; use remove_source or the app to change that').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true; the description carries far more: 3 credits per message, max 5 leads, ~10-40s per message, no auto-refund for failed generations, concurrency mis-attribution risk, and the exact idempotency reuse semantics. This is well beyond what the annotations provide and is consistent with a paid, mutating operation.
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 cost and scope are front-loaded, but the body is a dense run-on of nested clauses (promotion semantics, hiring-team drafting edge cases, skip rules) that is hard to parse in one pass. Much of the detail earns its place, yet the packaging is overly heavy for a tool description.
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-param, nested-object, mutation tool with no output schema, the description covers cost, timing, completion/readiness behavior, prerequisites, and concurrency. It references a 'promotion' return value without a schema to ground it, which is a small completeness gap.
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 only 14%, so the description must compensate, and it largely does: it explains the contact_ids/hiring_lead_ids split, the campaign_id reuse, the template_id vs inline_config exclusivity, and idempotency_key semantics. Minor gap: campaign_name is never mentioned.
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+resource ('Draft AI outreach messages') and immediately scopes it to warm leads sourced from list_warm_leads. It names the sibling tools (list_warm_leads, list_hiring_leads, list_templates) that supply its inputs, so an agent can distinguish it from other drafting/sourcing tools 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?
Gives explicit routing: use contact_ids for warm leads vs hiring_lead_ids for hiring leads, and template_id OR inline_config but not both. It also states operational constraints (one call per campaign, Business Profile required, fresh idempotency_key per batch) and names the alternative behavior for retries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true; the description adds meaningful context beyond that, including cost ('Free'), the access constraint that a preset is limited to Hiring leads, and a full inventory of the returned data categories. It does not discuss pagination or limits on template counts, which is a minor omission for a list tool.
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 main purpose is front-loaded in the first clause, but the rest is one sprawling sentence with nested parentheticals (the hiring_lead_ids aside and the long constraints enumeration) that is harder to parse than it needs to be. The content is largely load-bearing, but it would benefit from being split into shorter statements.
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 burden of describing returns, and it does so thoroughly: template fields, system presets, and the authoring constraints block. An agent can act on this without opening any schema.
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?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is empty and fully consistent with the parameterless description.
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 message templates) and immediately scopes it to the workspace, then enumerates exactly what comes back: system presets, saved templates, bodies, tone, language, AI variables, and authoring constraints. It is clearly distinguishable from siblings like save_template and draft_message, which it names as downstream consumers of the returned constraints.
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?
Explicitly frames the output as input for building a save_template or draft_message inline_config, which tells the agent when this tool is the right precursor. It also notes the Hiring LinkedIn DM preset is restricted to hiring_lead_ids and only Hiring leads can use it. It stops short of stating when-not to call it or naming an alternative lister, so it falls just short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. On a keyword, competitor_creator or Company page source each kind of person is in its own field: commenters in results.posts[].engagers, reactors in results.posts[].reactors; a post preview lists its commenters in results.posts[].engagers and only counts its reactors (results.posts[].num_likes), with no reactors field. A keyword, competitor_creator or Company page source set to reactors previews who reacted to its posts (results.engager_kind reactions); one set to both previews up to 2 commenters and 2 reactors on each shown post, with results.engager_kind both, while that is open to your workspace, and commenters only otherwise. A keyword source set to All (keyword_mode all) previews its post authors and up to 2 commenters and 2 reactors on each shown post, with results.engager_kind both, while All is open to your workspace, and its post authors and commenters only otherwise. 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: credit charges, refund policy for confirmed pre-acceptance failures, uncertain-call reconciliation, timing of roughly 10-60 seconds, empty-preview semantics, and source-type-specific preview behavior. These details align with the destructiveHint=true annotation because the tool can incur retained charges.
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 description is front-loaded with the core action, but it becomes a dense unbroken paragraph with long source-type and output-field clauses. Most information is relevant given the lack of schema coverage, but the lack of structure makes it harder to scan than it could be.
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?
Given the complexity, 0% schema description coverage, and no output schema, the description is unusually complete. It explains source-type-specific return fields, engagement semantics, credit and refund behavior, timing, and idempotency handling, leaving little an agent needs to infer before calling it.
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 explains source_type behavior extensively and gives clear idempotency_key semantics, but source_id is not explicitly defined beyond being the source identifier. The description therefore partially compensates for the schema gap.
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 clearly states a specific verb and resource: 'Run an optional live preview' of specified source types. It distinguishes among keyword, competitor_creator, Company page, Hiring, and paused post sources, though it does not explicitly compare this tool to sibling alternatives such as run_source_once.
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 word 'optional' and the idempotency guidance imply this is a preview step before a real run, but the description never explicitly states when to use this tool versus alternatives like run_source_once. Usage is left to inference rather than direct routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove (archive) a discovery source by its exact source ID. It stops the source's scheduled LinkedIn scans. Free. DESTRUCTIVE for monitoring: queued scan jobs are cancelled. Historical warm leads keep their source label, and re-adding the same creator, Company page, or post source later revives it with its history; a keyword source comes back when re-added with the keyword_mode it had.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds real value beyond them: queued scan jobs are cancelled, historical warm leads retain their source label, and re-adding the same creator/company/post source restores history while a keyword source needs its prior keyword_mode. The one gap is that it never states required permissions or whether removal is reversible on demand.
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 and the DESTRUCTIVE warning are front-loaded, then recovery behavior follows. Five sentences is slightly long and the revival clause is dense, but nearly every sentence carries non-obvious operational information, so little is wasted.
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-required-param destructive mutation with no output schema, the description covers the essentials: what is removed, what side effects occur (cancelled jobs), what survives (warm-lead labels), and how to undo it. An agent has enough to call it correctly and warn the user.
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% for the single source_id parameter, so the description carries the load. It stresses 'exact source ID' and even names the accepted source kinds (creator, Company page, post, keyword), which usefully prevents the agent from passing a fuzzy name or search term; only the UUID format expectation is left unstated.
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 precise verb plus resource plus scope: 'Remove (archive) a discovery source by its exact source ID.' The parenthetical 'archive' signals the soft-delete semantics that separate it from a hard delete, and the detail about stopping scheduled LinkedIn scans implicitly distinguishes it from cancel_source_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?
The description explains consequences well but never says when to reach for this tool versus the close alternatives cancel_source_run, preview_source, or set_source_schedule — all of which touch the same object. 'Free' hints that cost is not a blocker, but no explicit selection criteria or exclusions are given.
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. A keyword (post_engagers), creator or Company page source set to both takes commenters and reactors together from one budget, with no fixed split, while that is open to your workspace, and commenters only otherwise. A keyword source set to All (keyword_mode all) takes post authors, commenters and reactors together from one budget, with no fixed split, the best-fitting posts first under the default post order, while All is open to your workspace, and post authors and commenters only otherwise. 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). A one-time scan never pays a scan fee. Stage-2 charges/refunds normal wallet credits; a zero-engagement post completes with a net lead charge of 0. Leads land in Warm Leads within minutes; a keyword source (any keyword_mode), a creator source, or a Company page source adds the run's best people in one batch when the run finishes. 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it discloses credit charging and refunding, the fact that a one-time scan never pays a scan fee, zero-engagement charge behavior, the timing and batching of Warm Leads, and the fixed versus pooled allocation rules for post scope. These details are consistent with readOnlyHint=false and destructiveHint=true because the tool spends credits and writes leads.
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 purpose and scoping are front-loaded, and most clauses carry relevant operational detail. However, the description is a dense, long run-on with many conditional source-type rules, making it harder to parse than necessary for a four-parameter 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?
There is no output schema, so the description carries the burden of explaining results, and it does: it states that leads land in Warm Leads within minutes and that keyword, creator, and Company page sources add the run's best people in one batch when finished. Combined with the credit and cancellation behavior, this is complete enough for an agent to invoke the tool 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 50%, so the description meaningfully compensates by explaining confirm:true, max_credits as the backfill credit limit, and lookback_days as selecting 24 hours or 7 days for certain source types. It does not explicitly explain source_id semantics or confirm's default, but the schema covers the UUID format and required field.
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 and resource: run a discovery source once, and explicitly scopes it to active/paused keyword, creator, Company page, Hiring, or paused Once-only post sources. It also distinguishes the action from starting Daily monitoring or touching the schedule, so an agent can identify it without conflating it with scheduling or cancellation tools.
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 clearly says when to use this tool: for a one-time scan that should not start Daily monitoring or alter the schedule. It also names cancel_source_run as the cancellation alternative and clarifies that confirm:true plus max_credits are required, though it does not explicitly compare against preview_source or other read-only alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Show or set the workspace's total daily discovery budget: the most Discovery spends per day across all Daily and Custom sources, shared between them (a Run once or 7-day scan has its own limit). Without credits, returns the budget in force and who set it (saved_by: you, default or plan_cap), the default that Reset on the Sources page would save today, the most you can set (a paid plan: its monthly credits plus purchased credits; Free: 100 credits a day) and the credit balance. With credits, sets that number; 0 pauses discovery. A number saved here counts as your own choice, exactly as when you save it in the app; going back to the automatic default is done with Reset on the Sources page. Free to call. REQUIRES confirm:true to change the budget; without it returns a no-write plan.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| credits | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the write-gating rule (confirm:true required, otherwise a no-write plan is returned), the effect of 0 (pauses discovery), that the call is free, and the derivation of the maximum (plan monthly credits plus purchased credits; Free capped at 100/day). That is far richer than destructiveHint=true 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 dual-purpose statement and the confirm requirement are front-loaded and every clause carries information, but the single dense paragraph packs return-value details and plan rules into one long block that could be segmented for faster scanning. Information density is high with little true 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?
With no output schema, the description still explains the return shape (budget in force, saved_by: you/default/plan_cap, today's default, maximum settable, credit balance). For a two-parameter, write-gated tool this covers everything an agent needs to call and interpret it.
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 parameter burden and does so: credits' semantics (sets the number, 0 pauses, bounds derived from plan), and confirm's role as the write gate with its no-write fallback. Both parameters are fully interpretable without schema documentation.
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 — show or set the workspace's total daily discovery budget — and defines exactly what that budget covers (all Daily and Custom sources, shared, excluding Run once/7-day scans). The dual read/write behavior is disambiguated by the credits parameter, so an agent knows precisely what the call will do.
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?
Explicitly splits the two modes: omit credits to read the budget, saved_by, default and max; supply credits to set it; 0 pauses discovery. It also names the alternative path for reverting to automatic defaults (Reset on the Sources page) and states that a value saved here is treated as the user's own choice.
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: a scheduled scan that brings you nobody pays a scan fee of 1 credit. 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=true; the description goes far beyond by disclosing the confirm:true requirement (and no-write plan without it), credit costs (1 credit scan fee), the timing effects of saving (next scan due now, custom takes effect at next selected day), and that re-saving an identical schedule is a no-op. This is exactly the extra context annotations cannot carry.
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 scope before the operational details, and nearly every clause adds actionable information. It is a dense run-on paragraph that could be broken into shorter statements, but little is wasted.
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 multi-parameter mutation tool with no output schema, the description supplies everything needed: target identification, schedule semantics, confirm requirement, and side effects on scan timing and credits. An agent can invoke it correctly without further inference.
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 load, and it does: source_id accepts UUID or exact name, a Hiring source's name is its label with an example, custom weekdays use ISO numbering (1=Monday..7=Sunday), and the single local_time applies to every selected weekday in an IANA timezone. It even covers the confirm flag's semantics.
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 (Set) and resource (schedule) and enumerates the exact source types it applies to (keyword, competitor/creator, Company page, Hiring discovery source). This clearly distinguishes it from siblings like run_source_once, preview_source, and add_source.
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 usage context, including a when-not case ('Post sources are Once-only and reject schedules') and behavioral rules for switching an active source to Daily vs Custom. It does not name an alternative sibling tool for the rejected cases, so it stops short of full when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_source2 fields changedInput schema / properties / keyword_mode / descriptionPrevious value: -"Keyword only: both (Authors + commenters: post authors and their commenters), post_engagers (commenters and reactors together, from one budget, while that is open to your workspace, otherwise commenters; post_engagement_scope commenters or reactors narrows it) or post_authors. When omitted: both, or the mode of the keyword's active source."New value: +"Keyword only: all (post authors, commenters and reactors from one budget; refused while it is not open to your workspace), post_engagers (commenters and reactors together, from one budget, while that is open to your workspace, otherwise commenters; post_engagement_scope commenters or reactors narrows it), post_authors, or both (Authors + commenters: post authors and their commenters; an All source given both becomes Authors + commenters). When omitted: the mode of the keyword's active source when it has one in another mode; otherwise a new source is all while All is open to your workspace and both when it is not, and an existing source keeps its audience."Input schema / properties / keyword_mode / enumPrevious value: -[
- "both",
- "post_engagers",
- "post_authors"
-]New value: +[
+ "all",
+ "both",
+ "post_engagers",
+ "post_authors"
+]add_source2 fields changedInput schema / properties / keyword_mode / descriptionPrevious value: -"Keyword only: both (Authors + commenters: post authors and their commenters), post_engagers (commenters; with post_engagement_scope reactors, reactors; with both, commenters and reactors) or post_authors. When omitted: both, or the mode of the keyword's active source."New value: +"Keyword only: both (Authors + commenters: post authors and their commenters), post_engagers (commenters and reactors together, from one budget, while that is open to your workspace, otherwise commenters; post_engagement_scope commenters or reactors narrows it) or post_authors. When omitted: both, or the mode of the keyword's active source."Input schema / properties / post_engagement_scope / descriptionPrevious value: -"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters, reactors or both (commenters and reactors together, from one budget); omitted keeps the saved choice. A new competitor_creator or company source without it takes both while that is open to your workspace, otherwise commenters; a new keyword source takes commenters. Reactors and both on these sources are refused while they are not open to your workspace."New value: +"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters, reactors or both (commenters and reactors together, from one budget); omitted keeps the saved choice. A new keyword (post_engagers), competitor_creator or company source without it takes both while that is open to your workspace, otherwise commenters. Reactors and both on these sources are refused while they are not open to your workspace."add_source1 field changedInput schema / properties / keyword_mode / descriptionPrevious value: -"Keyword only: both (post authors and commenters), post_engagers (commenters; with post_engagement_scope reactors, reactors; with both, commenters and reactors) or post_authors. When omitted: both, or the mode of the keyword's active source."New value: +"Keyword only: both (Authors + commenters: post authors and their commenters), post_engagers (commenters; with post_engagement_scope reactors, reactors; with both, commenters and reactors) or post_authors. When omitted: both, or the mode of the keyword's active source."add_source2 fields changedInput schema / properties / keyword_mode / descriptionPrevious value: -"Keyword only: both (post authors and commenters), post_engagers (commenters) or post_authors. When omitted: both, or the mode of the keyword's active source."New value: +"Keyword only: both (post authors and commenters), post_engagers (commenters; with post_engagement_scope reactors, reactors; with both, commenters and reactors) or post_authors. When omitted: both, or the mode of the keyword's active source."Input schema / properties / post_engagement_scope / descriptionPrevious value: -"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters or reactors; omitted keeps the saved choice (commenters for a new source). Reactors on these sources are refused while they are not open to your workspace."New value: +"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters, reactors or both (commenters and reactors together, from one budget); omitted keeps the saved choice. A new competitor_creator or company source without it takes both while that is open to your workspace, otherwise commenters; a new keyword source takes commenters. Reactors and both on these sources are refused while they are not open to your workspace."add_source1 field changedInput schema / properties / post_engagement_scope / descriptionPrevious value: -"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters or reactors; omitted keeps the saved choice (commenters for a new source). Reactors on these sources are in beta and refused while the service has them switched off."New value: +"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters or reactors; omitted keeps the saved choice (commenters for a new source). Reactors on these sources are refused while they are not open to your workspace."add_source1 field changedInput schema / properties / post_engagement_scope / descriptionAdded value: +"Who the source takes from its posts. post: commenters, reactors or both (default both). keyword (with keyword_mode post_engagers), competitor_creator and company: commenters or reactors; omitted keeps the saved choice (commenters for a new source). Reactors on these sources are in beta and refused while the service has them switched off."set_daily_budgetadd_source2 fields changedInput schema / properties / keyword_mode / descriptionAdded value: +"Keyword only: both (post authors and commenters), post_engagers (commenters) or post_authors. When omitted: both, or the mode of the keyword's active source."Input schema / properties / keyword_mode / enumPrevious value: -[
- "post_engagers",
- "post_authors"
-]New value: +[
+ "both",
+ "post_engagers",
+ "post_authors"
+]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.
Find warm leads on LinkedIn: people who engage with your team, competitors and market.
AI agent for LinkedIn outreach: finds the right people, writes in your voice, follows up, replies.
Add one secure layer between your agents and this server.
