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. 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

TableJSON 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
industriesNo
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.
company_headcountNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
  2. 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"
      +}
  3. 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"
      +}
  4. 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"
      +}
  5. 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."
  6. 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."
  7. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false / destructiveHint=true / openWorldHint=true; the description adds far more: 0.25 credits per lead, a 3-credit minimum, free zero-result calls, budget_credits acting as a ceiling that lowers limit rather than enabling pricier sources, and dry_run performing no lookup, reservation or charge. It also warns that returned leads carry work_email=null and explains title_filter.withheld, which no annotation conveys.

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?

Front-loads purpose well, but the final sentences duplicate the route enum and its default straight from the schema ('balanced (the default), cheapest, broadest or fastest'), and the sentence is convoluted and contains a typo ('layrcake.route'). Several sentences are overloaded where bullets would serve better.

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?

With no output schema, the description carries the return burden and does so reasonably: work_email is null, title_filter.withheld is surfaced, result.budget_applied and the route echo are named. It is only incomplete on the required 'audience' parameter, whose semantics are never stated.

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 beyond the 46%-covered schema: LinkedIn industry taxonomy, the semantics of company_domains as a company-level restriction, and headcount ranges. Gaps remain — the single required parameter 'audience' is never explained in prose (only shown inside the example), and the stated 'up to 100 domains' conflicts with the schema's maxItems of 200.

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, resource and scale ('Search 200M+ B2B contacts by structured filters') and immediately enumerates the filter axes, so an agent knows exactly what class of tool this is. It is clearly distinguishable from siblings like find_companies or enrich.

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

Usage Guidelines4/5

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

States a hard precondition ('at least one of titles, industries, locations, or company_domains is required') and explains the situations for dry_run, premium and offer_token. However, it never names an alternative tool (e.g. find_companies) or says when not to use this one, so routing among siblings is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources