Skip to main content
Glama

Find leads

find_leads
Destructive

Search 200M+ B2B contacts by structured filters (titles, locations, industries, company_headcount, company_domains). At least one of titles, industries, locations, or company_domains is required. company_domains accepts up to 100 domains or URLs and restricts results to people at those companies. Industry values follow LinkedIn's taxonomy (for example, 'Hospitals and Health Care'). Returned leads have work_email null. If title_filter.withheld is above 0, the sources found people whose titles did not match; widen titles to see them. Costs 0.25 credits per lead returned, with a 3-credit minimum when any lead is returned; zero results are free. To reach people at a kind of company that titles and industries can't pin down, find the companies first with find_companies, then call find_leads with their company_domains. budget_credits is a spend ceiling, never permission to use a dearer source: when the call could cost more, limit is lowered to the largest that fits and result.budget_applied says so. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"audience":"Heads of Sales and VPs of Sales at US software companies with 50 to 500 employees","titles":["Head of Sales","VP Sales"],"industries":["Software Development"],"locations":["United States"],"company_headcount":{"min":50,"max":500},"limit":25} route picks how sources are chosen: balanced (the default), cheapest, broadest or fastest. The price is the same whichever you pick, and the answer's layrcake.route says which route was used and whether it came from the request, this key's default or the default.

Input Schema

NameRequiredDescriptionDefault
limitNo
routeNoSource preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted.
titlesNo
dry_runNoReturn this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason.
premiumNoConsent, for this call only, to a dearer source when the standard sources come back short, as long as the whole call, the premium step included, stays within budget_credits (which it requires). The premium step is charged separately and reported in result.premium_step. Without it, budget_credits is only a ceiling. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.
audienceYes
locationsNo
industriesNoLinkedIn industry names, for example "Hospitals and Health Care" or "Software Development".
offer_tokenNoAccept a previous answer's offer: send the same call again, unchanged, with its offer.offer_token. Only the premium step runs, as its own charge at the offer's price, up to its max_credits; the token works once, until expires_at, and only when max_credits is within this key's premium allowance. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.
budget_creditsNoSpend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one lead fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason.
company_domainsNo
idempotency_keyNoA payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that.
include_handledNoOnly inside an agent run: true includes people this agent already put in a campaign in the last 90 days, which the run's searches otherwise leave out. Outside an agent run it changes nothing.
company_headcountNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / include_handled
      Added value: +{
      +  "description": "Only inside an agent run: true includes people this agent already put in a campaign in the last 90 days, which the run's searches otherwise leave out. Outside an agent run it changes nothing.",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / industries / description
      Added value: +"LinkedIn industry names, for example \"Hospitals and Health Care\" or \"Software Development\"."
  3. Changed1 schema field changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."
  4. Changed2 schema fields changed
    • addedInput schema / properties / offer_token
      Added value: +{
      +  "description": "Accept a previous answer's offer: send the same call again, unchanged, with its offer.offer_token. Only the premium step runs, as its own charge at the offer's price, up to its max_credits; the token works once, until expires_at, and only when max_credits is within this key's premium allowance. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.",
      +  "pattern": "^lc_offer_[A-Za-z0-9_-]{43}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / premium
      Added value: +{
      +  "const": "within_budget",
      +  "description": "Consent, for this call only, to a dearer source when the standard sources come back short, as long as the whole call, the premium step included, stays within budget_credits (which it requires). The premium step is charged separately and reported in result.premium_step. Without it, budget_credits is only a ceiling. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason.",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / route
      Added value: +{
      +  "description": "Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted.",
      +  "enum": [
      +    "balanced",
      +    "cheapest",
      +    "broadest",
      +    "fastest"
      +  ],
      +  "type": "string"
      +}
  6. Changed2 schema fields changed
    • addedInput schema / properties / budget_credits
      Added value: +{
      +  "description": "Spend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one lead fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 2000,
      +  "type": "number"
      +}
    • addedInput schema / properties / dry_run
      Added value: +{
      +  "description": "Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason.",
      +  "type": "boolean"
      +}
  7. Changed1 schema field changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Optional for search and enrichment tools: supply one to make a retry replay the original result. Required for tools that create an external side effect; reuse the same value after a timeout or an approval."New value: +"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."
  8. Changed1 schema field changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Stable retry key; the same value identifies retries of the same request after timeout or approval."New value: +"Optional for search and enrichment tools: supply one to make a retry replay the original result. Required for tools that create an external side effect; reuse the same value after a timeout or an approval."
  9. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Adds substantial context beyond the annotations: exact pricing (0.25 credits/lead, 3-credit minimum, zero results free), that leads come back with work_email null, that title_filter.withheld signals non-matching titles, and that dry_run reserves and charges nothing. With destructive/openWorld already declared by annotations, the money-spend disclosure is the missing piece and it is covered well. It does not explain the destructiveHint implication beyond cost, which keeps it off a 5.

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

Conciseness3/5

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

The first third is front-loaded and efficient, but the tail becomes a run-on that repeats what the schema already documents for route and budget_credits ('The price is the same whichever you pick...') and ends with a garbled reference ('the answer's layrcake.route'). Several sentences could be trimmed without losing decision-relevant information.

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

Completeness4/5

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

For a 14-parameter, nested-object, cost-bearing search tool with no output schema, the description covers the essentials an agent needs: the required-filter rule, pricing and minimums, budget lowering behavior, dry-run planning, source routing, and a worked example. The premium/offer_token flow and the return payload shape are left to the schema, which is acceptable but leaves a small gap.

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

Parameters4/5

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

Adds real meaning over the 57%-covered schema: which filters satisfy the required-filter constraint, the LinkedIn taxonomy for industries, and what company_domains does to results ('restricts results to people at those companies'), plus budget_credits and route behavior tied to result fields. One inconsistency: it says company_domains accepts 'up to 100 domains' while the schema sets maxItems to 200, and premium/offer_token/idempotency_key are left entirely to the schema.

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

Purpose5/5

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

Opens with a specific verb and resource plus scale: 'Search 200M+ B2B contacts by structured filters', then enumerates the filter families. It explicitly distinguishes itself from the sibling find_companies by stating when to use that tool first and then come back with company_domains.

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

Usage Guidelines5/5

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

Gives a hard prerequisite ('At least one of titles, industries, locations, or company_domains is required'), a routing rule to the sibling tool for a specific intent ('a kind of company that titles and industries can't pin down'), and guidance on when to use dry_run versus a real call. The budget_credits paragraph also clarifies the ceiling-vs-permission distinction that would otherwise cause misuse.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources