Generect

Search leads (free thin rows, full rows billed)

search_leads

Return leads (people) matching an ICP. FREE by default while the account has free thin rows left today (daily quota; see detail — pass detail "thin" to guarantee $0). detail "full" is billable, about $0.0067 per returned row (0 rows costs $0) (Tier 0 list price; your account may pay a different rate — call get_balance for your real prices, and read cost.amount_charged in every response for what was actually spent). Realtime, or an auto escalation to it, is billed per row too. Run count_leads first — it is free and sizes the audience. Rows never include email or phone: call generate_email (it takes the lead id) or find_phone only on the ids you keep. Ordering is not stable, so paginate by passing ids you already have in exclude_ids rather than by offset.

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	Data mode. "database" = Generect's own index: sub-second, free counts, free thin rows (see detail) or cheaper full rows; it accepts a subset of the filters today and names any it rejects. "realtime" = live LinkedIn lookup, 5–60s, billed per row, accepts every realtime filter. "auto" (default) tries database first and escalates to realtime only if a filter you passed is rejected there (the escalation is reported, and is refused above the per-call spend ceiling). Pick "database" explicitly when freshness is not critical and cost matters more than freshness.
`limit`	No	Alias for limit_by.
`detail`	No	Row detail for the database search. Thin rows are FREE — id, name, job_title, seniority, location, company name/id/industry/country; no LinkedIn URL, domain, contacts or history — up to a daily per-account row quota that resets at 00:00 UTC. Omitted (default): thin while the free tier is available; once it is not (quota spent, a custom-contract account, a server without the tier) the search continues as before — full rows billed per row, marked thin_unavailable in the result, under the spend ceiling. "thin": free rows only — never billed, never escalated to realtime; a spent quota is a 429 and a realtime-only filter is an error. "full": the whole record, billed per row. Browse thin, then spend only on the rows you keep: generate_email takes the lead id directly, enrich_* gives the full record.
`offset`	No	Alias for offset_by.
`strict`	No	Fields to match strictly, e.g. ["company_locations"].
`compact`	No	Default true: return a small per-lead summary (including the Generect `id`, which every later step accepts). Set false for the full raw record (~80 fields) — only worth it when you specifically need skills, education or other deep fields.
`keywords`	No	Free-text keywords across headline/summary/skills — realtime only: using it forces the pricier live mode.
`limit_by`	No	Rows to return this call (1–100, default 25). You are billed per returned row, so this number IS the price of the call.
`personas`	No	Advanced raw persona tuples [name, functions, seniorities, prohibits, priority?] — realtime only: using it forces the pricier live mode.
`functions`	No	Job functions, e.g. ["Sales","Marketing","Engineering"] — realtime only: using it forces the pricier live mode.
`job_title`	No	DEPRECATED alias for job_titles. Still honoured: it is merged into job_titles.
`locations`	No	Where the lead lives — matches cities, states and countries, e.g. ["United States","Berlin"].
`offset_by`	No	Rows to skip (pagination).
`company_id`	No	Anchor to one company by LinkedIn numeric id.
`job_titles`	No	Target job titles, OR-matched (e.g. ["CEO","Founder","Owner"]). A lead needs to match only one.
`timeout_ms`	No	Request timeout in milliseconds.
`exclude_ids`	No	Skip leads by Generect/Sales-Navigator id. Pass the ids you already received to paginate without duplicates — ordering is not stable, so this is more reliable than offset.
`seniorities`	No	Seniority at the current employer, e.g. ["Owner","CXO","VP","Director","Manager"]. Current position only.
`changed_jobs`	No	Only leads who recently changed jobs — realtime only: using it forces the pricier live mode.
`company_link`	No	Anchor to one company by LinkedIn URL.
`company_name`	No	Anchor to one company by name (exclusive with company_link/company_id).
`company_types`	No	Employer types: "Public Company","Privately Held","Non Profit","Government Agency","Educational","Self Employed","Self Owned","Partnership".
`exclude_names`	No	Skip leads by full name. Works in both modes (the database-mode bug that returned 0 rows was fixed in the API on 2026-08-13, PRO-1333). exclude_ids is still the more reliable way to paginate.
`get_max_leads`	No	DEPRECATED — accepted but ignored. Always on now: search responses include results_count without asking.
`company_filters`	No	Optional: only return leads at companies matching these filters (two-level ICP).
`lead_industries`	No	DEPRECATED — accepted but ignored. Removed: v1 filters on the employer's industry. Use company_industries.
`without_company`	No	DEPRECATED — accepted but ignored. No longer needed — v1 filter-only search is the default when no company anchor is set.
`years_in_company`	No	Time at current company, same buckets as years_in_position — realtime only: using it forces the pricier live mode.
`company_locations`	No	HQ location of the lead's current employer.
`confirm_spend_usd`	No	Explicit approval for an unusually large charge. Calls whose worst case exceeds $5 are refused unless this is set to at least the amount the tool reports. Only set it after the user has agreed to that number.
`exclude_locations`	No	Lead locations to exclude.
`filter_empty_vars`	No	Drop leads where these fields are empty, e.g. ["profile_photo","job_started_on"]. Useful to raise data quality before paying.
`years_in_position`	No	Time in current role: 1=<1y, 2=1-2y, 3=3-5y, 4=6-10y, 5=10y+ — realtime only: using it forces the pricier live mode.
`company_headcounts`	No	Employer size buckets. Allowed ONLY: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10 000+" (note the space in "10 000+").
`company_industries`	No	Industry of the current employer. Must match Generect industry names exactly (e.g. "Software Development", "Financial Services"); names are hierarchical and unknown names are rejected with HTTP 400 naming the field.
`past_company_names`	No	Companies the lead previously worked at (alumni targeting) — realtime only: using it forces the pricier live mode.
`posted_on_linkedin`	No	Only leads who recently posted on LinkedIn — realtime only: using it forces the pricier live mode.
`linkedin_filter_link`	No	A LinkedIn / Sales Navigator search URL to lift filters from — realtime only: using it forces the pricier live mode.
`allow_unlisted_values`	No	Escape hatch. This server checks industry / seniority / headcount / company-type values against the LinkedIn vocabularies before sending, because the API silently returns 0 results for an unknown industry or seniority instead of rejecting it. Set true only when you are sure a value is valid and this server is out of date.
`exclude_title_keywords`	No	DEPRECATED — accepted but ignored. No v1 equivalent. Narrow job_titles instead, or filter the returned rows yourself.
`exclude_company_locations`	No	Employer HQ locations to exclude.
`exclude_company_headcounts`	No	Employer size buckets to exclude.
`exclude_company_industries`	No	Employer industries to exclude.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`fix`	No
`cost`	No
`mode`	No
`note`	No
`leads`	No
`status`	No
`returned`	No
`companies`	No
`test_mode`	No
`spend_guard`	No
`results_count`	No
`next_page_args`	No
`requested_rows`	No
`escalation_note`	No
`test_mode_notice`	No
`vocabulary_warnings`	No
`blocked_by_vocabulary`	No
`deprecated_params_ignored`	No
`escalated_to_realtime_because`	No
`api_returned_more_than_requested`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedOct 7, 2026
- changedInput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / company_filters / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / company_filters / properties / department_headcount / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / company_filters / properties / headcount_growth / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / company_filters / properties / revenues_range / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / personas / items
```
Added value: +{}
```
- changedOutput schema / $schema
```
Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
```
- removedOutput schema / properties / blocked_by_vocabulary / $ref
```
Removed value: -"#/properties/vocabulary_warnings"
```
- addedOutput schema / properties / blocked_by_vocabulary / items
```
Added value: +{}
```
- addedOutput schema / properties / blocked_by_vocabulary / type
```
Added value: +"array"
```
- addedOutput schema / properties / companies / items
```
Added value: +{}
```
- addedOutput schema / properties / deprecated_params_ignored / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / leads / items
```
Added value: +{}
```
- addedOutput schema / properties / vocabulary_warnings / items
```
Added value: +{}
```

Changed3 schema fields changedOct 6, 2026

addedInput schema / properties / detail

Added value: +{
+  "description": "Row detail for the database search. Thin rows are FREE — id, name, job_title, seniority, location, company name/id/industry/country; no LinkedIn URL, domain, contacts or history — up to a daily per-account row quota that resets at 00:00 UTC. Omitted (default): thin while the free tier is available; once it is not (quota spent, a custom-contract account, a server without the tier) the search continues as before — full rows billed per row, marked thin_unavailable in the result, under the spend ceiling. \"thin\": free rows only — never billed, never escalated to realtime; a spent quota is a 429 and a realtime-only filter is an error. \"full\": the whole record, billed per row. Browse thin, then spend only on the rows you keep: generate_email takes the lead id directly, enrich_* gives the full record.",
+  "enum": [
+    "thin",
+    "full"
+  ],
+  "type": "string"
+}

changedInput schema / properties / exclude_names / description

Previous value: -"Skip leads by full name. KNOWN ISSUE: in database mode any non-empty value collapses the result set to 0 (verified 2026-08-09); it behaves correctly in realtime mode. Prefer exclude_ids, or filter names out yourself after the search."New value: +"Skip leads by full name. Works in both modes (the database-mode bug that returned 0 rows was fixed in the API on 2026-08-13, PRO-1333). exclude_ids is still the more reliable way to paginate."

changedInput schema / properties / mode / description

Previous value: -"Data mode. \"database\" = cached, sub-second, cheaper, free counts, core filters only. \"realtime\" = live LinkedIn lookup, 5–60s, pricier, supports every filter. \"auto\" (default) tries database first and only escalates to realtime if a filter you passed is unsupported there — an escalation is reported in the response. Pick \"database\" explicitly when freshness is not critical and cost matters more than freshness."New value: +"Data mode. \"database\" = Generect's own index: sub-second, free counts, free thin rows (see detail) or cheaper full rows; it accepts a subset of the filters today and names any it rejects. \"realtime\" = live LinkedIn lookup, 5–60s, billed per row, accepts every realtime filter. \"auto\" (default) tries database first and escalates to realtime only if a filter you passed is rejected there (the escalation is reported, and is refused above the per-call spend ceiling). Pick \"database\" explicitly when freshness is not critical and cost matters more than freshness."

Changed4 schema fields changedSep 24, 2026

addedInput schema / properties / allow_unlisted_values

Added value: +{
+  "description": "Escape hatch. This server checks industry / seniority / headcount / company-type values against the LinkedIn vocabularies before sending, because the API silently returns 0 results for an unknown industry or seniority instead of rejecting it. Set true only when you are sure a value is valid and this server is out of date.",
+  "type": "boolean"
+}

addedInput schema / properties / company_filters / properties / allow_unlisted_values

Added value: +{
+  "description": "Escape hatch for the local vocabulary check — see the lead-side field of the same name.",
+  "type": "boolean"
+}

addedInput schema / properties / confirm_spend_usd

Added value: +{
+  "description": "Explicit approval for an unusually large charge. Calls whose worst case exceeds $5 are refused unless this is set to at least the amount the tool reports. Only set it after the user has agreed to that number.",
+  "type": "number"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "api_returned_more_than_requested": {
+      "type": "number"
+    },
+    "blocked_by_vocabulary": {
+      "$ref": "#/properties/vocabulary_warnings"
+    },
+    "companies": {
+      "type": "array"
+    },
+    "cost": {
+      "additionalProperties": false,
+      "properties": {
+        "amount_charged_usd": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "billed": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "operation": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "deprecated_params_ignored": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "escalated_to_realtime_because": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "escalation_note": {
+      "type": "string"
+    },
+    "fix": {
+      "type": "string"
+    },
+    "leads": {
+      "type": "array"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "next_page_args": {},
+    "note": {
+      "type": "string"
+    },
+    "requested_rows": {
+      "type": "number"
+    },
+    "results_count": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "returned": {
+      "type": "number"
+    },
+    "spend_guard": {},
+    "status": {
+      "type": "string"
+    },
+    "test_mode": {
+      "type": "boolean"
+    },
+    "test_mode_notice": {
+      "type": "string"
+    },
+    "vocabulary_warnings": {
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

Changed46 schema fields changedSep 10, 2026

changedInput schema / properties / changed_jobs / description

Previous value: -"Only leads who recently changed jobs."New value: +"Only leads who recently changed jobs — realtime only: using it forces the pricier live mode."

changedInput schema / properties / compact / description

Previous value: -"Default true: return a 9-field summary per lead (name/title/company/industry/location/linkedin_url). Set false for the full raw lead object (skills, experience, etc.). Neither mode includes email — use generate_email."New value: +"Default true: return a small per-lead summary (including the Generect `id`, which every later step accepts). Set false for the full raw record (~80 fields) — only worth it when you specifically need skills, education or other deep fields."

addedInput schema / properties / company_filters

Added value: +{
+  "additionalProperties": false,
+  "description": "Optional: only return leads at companies matching these filters (two-level ICP).",
+  "properties": {
+    "company_names": {
+      "description": "Restrict to specific company names — realtime only: using it forces the pricier live mode.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "company_types": {
+      "description": "Company types: \"Public Company\",\"Privately Held\",\"Non Profit\",\"Government Agency\",\"Educational\", …",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "department_headcount": {
+      "additionalProperties": false,
+      "description": "Department size, e.g. {\"name\":\"engineering\",\"min\":10,\"max\":100} — realtime only: using it forces the pricier live mode.",
+      "properties": {
+        "max": {
+          "type": "number"
+        },
+        "min": {
+          "type": "number"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
+    "exclude_domains": {
+      "description": "Exclude companies by domain (e.g. existing customers).",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "exclude_ids": {
+      "description": "Exclude companies by LinkedIn id/URN.",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ]
+      },
+      "type": "array"
+    },
+    "exclude_industries": {
+      "description": "Industries to exclude.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "exclude_locations": {
+      "description": "HQ locations to exclude.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "headcount_growth": {
+      "additionalProperties": false,
+      "description": "Headcount growth in percent — realtime only: using it forces the pricier live mode.",
+      "properties": {
+        "max": {
+          "type": "number"
+        },
+        "min": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "headcounts": {
+      "description": "Size buckets. Allowed ONLY: \"1-10\",\"11-50\",\"51-200\",\"201-500\",\"501-1000\",\"1001-5000\",\"5001-10000\",\"10 000+\".",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "hiring_on_linkedin": {
+      "description": "Only companies actively hiring — realtime only: using it forces the pricier live mode.",
+      "type": "boolean"
+    },
+    "industries": {
+      "description": "Company industries. Must match Generect industry names exactly (e.g. \"Software Development\"); unknown names are rejected with HTTP 400.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "keywords": {
+      "description": "Free-text keywords across name/description/specialties — realtime only: using it forces the pricier live mode.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "linkedins_links": {
+      "description": "Specific LinkedIn company URLs — realtime only: using it forces the pricier live mode.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "locations": {
+      "description": "HQ locations — cities, states or countries.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "num_of_followers": {
+      "description": "LinkedIn follower buckets: \"1-50\",\"51-100\",\"101-1000\",\"1001-5000\",\"5001+\" — realtime only: using it forces the pricier live mode.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "revenues_range": {
+      "additionalProperties": false,
+      "description": "Annual revenue range, single object {min,max} — realtime only: using it forces the pricier live mode.",
+      "properties": {
+        "max": {
+          "type": "number"
+        },
+        "min": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "min",
+        "max"
+      ],
+      "type": "object"
+    },
+    "sub_industries": {
+      "description": "Expand each selected industry to its sub-industries as well (broadens the match).",
+      "type": "boolean"
+    },
+    "technologies": {
+      "description": "Technologies the company uses — realtime only: using it forces the pricier live mode.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / company_id / description

Previous value: -"Anchor to a specific LinkedIn company id (returns its employees; this branch is less deterministic and does not enforce lead_industries)."New value: +"Anchor to one company by LinkedIn numeric id."

changedInput schema / properties / company_id / type

Previous value: -"string"New value: +[
+  "string",
+  "number"
+]

changedInput schema / properties / company_industries / description

Previous value: -"Filter by the lead employer's industry (same taxonomy as lead_industries)."New value: +"Industry of the current employer. Must match Generect industry names exactly (e.g. \"Software Development\", \"Financial Services\"); names are hierarchical and unknown names are rejected with HTTP 400 naming the field."

changedInput schema / properties / company_link / description

Previous value: -"Anchor to a specific LinkedIn company URL."New value: +"Anchor to one company by LinkedIn URL."

changedInput schema / properties / company_locations / description

Previous value: -"Filter by the employer HQ location (country/region names)."New value: +"HQ location of the lead's current employer."

changedInput schema / properties / company_name / description

Previous value: -"Anchor to a specific company by name."New value: +"Anchor to one company by name (exclusive with company_link/company_id)."

changedInput schema / properties / company_types / description

Previous value: -"Employer types: \"Public Company\",\"Educational\",\"Self Employed\",\"Government Agency\",\"Non Profit\",\"Self Owned\",\"Privately Held\",\"Partnership\"."New value: +"Employer types: \"Public Company\",\"Privately Held\",\"Non Profit\",\"Government Agency\",\"Educational\",\"Self Employed\",\"Self Owned\",\"Partnership\"."

addedInput schema / properties / exclude_company_headcounts

Added value: +{
+  "description": "Employer size buckets to exclude.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_company_industries

Added value: +{
+  "description": "Employer industries to exclude.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_company_locations

Added value: +{
+  "description": "Employer HQ locations to exclude.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / exclude_ids / description

Previous value: -"sales_ids to exclude — pass the ids of leads already returned in prior calls to paginate/deduplicate."New value: +"Skip leads by Generect/Sales-Navigator id. Pass the ids you already received to paginate without duplicates — ordering is not stable, so this is more reliable than offset."

addedInput schema / properties / exclude_locations

Added value: +{
+  "description": "Lead locations to exclude.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / exclude_names / description

Previous value: -"Full names to exclude from results."New value: +"Skip leads by full name. KNOWN ISSUE: in database mode any non-empty value collapses the result set to 0 (verified 2026-08-09); it behaves correctly in realtime mode. Prefer exclude_ids, or filter names out yourself after the search."

changedInput schema / properties / exclude_title_keywords / description

Previous value: -"Title keywords to exclude from persona matching. Defaults to [assistant, intern, junior, student, trainee]; pass [] to disable."New value: +"DEPRECATED — accepted but ignored. No v1 equivalent. Narrow job_titles instead, or filter the returned rows yourself."

removedInput schema / properties / exclude_title_keywords / items
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / exclude_title_keywords / type
```
Removed value: -"array"
```

addedInput schema / properties / filter_empty_vars

Added value: +{
+  "description": "Drop leads where these fields are empty, e.g. [\"profile_photo\",\"job_started_on\"]. Useful to raise data quality before paying.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / functions / description

Previous value: -"Job functions (LinkedIn Sales-Nav categories, e.g. [\"Engineering\",\"Operations\",\"Marketing\",\"Sales\",\"Finance\"]). Validated by the API."New value: +"Job functions, e.g. [\"Sales\",\"Marketing\",\"Engineering\"] — realtime only: using it forces the pricier live mode."

changedInput schema / properties / get_max_leads / description

Previous value: -"Also report the total number of matching leads (results_count). The number of rows returned is still bounded by limit_by."New value: +"DEPRECATED — accepted but ignored. Always on now: search responses include results_count without asking."

removedInput schema / properties / get_max_leads / type
```
Removed value: -"boolean"
```

changedInput schema / properties / job_title / description

Previous value: -"Single job title (e.g., \"CEO\"). For multiple titles use job_titles."New value: +"DEPRECATED alias for job_titles. Still honoured: it is merged into job_titles."

changedInput schema / properties / job_titles / description

Previous value: -"One or more target job titles, OR-matched (e.g. [\"CEO\",\"Founder\",\"Owner\",\"President\"]). Preferred over job_title. Assistant/intern/junior/student/trainee are excluded by default; override with exclude_title_keywords."New value: +"Target job titles, OR-matched (e.g. [\"CEO\",\"Founder\",\"Owner\"]). A lead needs to match only one."

changedInput schema / properties / keywords / description

Previous value: -"Free-text keywords matched against the profile (Boolean phrases allowed)."New value: +"Free-text keywords across headline/summary/skills — realtime only: using it forces the pricier live mode."

changedInput schema / properties / lead_industries / description

Previous value: -"Lead personal-industry filter. Must match Generect industry names exactly (e.g. \"Financial Services\", \"IT Services and IT Consulting\"). Names are hierarchical (Financial Services includes Banking/Insurance). Invalid names are rejected (HTTP 400)."New value: +"DEPRECATED — accepted but ignored. Removed: v1 filters on the employer's industry. Use company_industries."

removedInput schema / properties / lead_industries / items
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / lead_industries / type
```
Removed value: -"array"
```

changedInput schema / properties / limit / description

Previous value: -"Alias for limit_by"New value: +"Alias for limit_by."

changedInput schema / properties / limit_by / description

Previous value: -"Total leads to return this call (1–100, default 25). This is a TOTAL cap across all personas. For more, paginate with exclude_ids."New value: +"Rows to return this call (1–100, default 25). You are billed per returned row, so this number IS the price of the call."

addedInput schema / properties / linkedin_filter_link

Added value: +{
+  "description": "A LinkedIn / Sales Navigator search URL to lift filters from — realtime only: using it forces the pricier live mode.",
+  "type": "string"
+}

changedInput schema / properties / locations / description

Previous value: -"Lead location filter — country/region names, e.g. [\"United States\",\"Canada\"]."New value: +"Where the lead lives — matches cities, states and countries, e.g. [\"United States\",\"Berlin\"]."

addedInput schema / properties / mode

Added value: +{
+  "description": "Data mode. \"database\" = cached, sub-second, cheaper, free counts, core filters only. \"realtime\" = live LinkedIn lookup, 5–60s, pricier, supports every filter. \"auto\" (default) tries database first and only escalates to realtime if a filter you passed is unsupported there — an escalation is reported in the response. Pick \"database\" explicitly when freshness is not critical and cost matters more than freshness.",
+  "enum": [
+    "auto",
+    "database",
+    "realtime"
+  ],
+  "type": "string"
+}

changedInput schema / properties / offset / description

Previous value: -"Alias for offset_by"New value: +"Alias for offset_by."

changedInput schema / properties / offset_by / description

Previous value: -"Offset for pagination (note: ordering is not stable — exclude_ids is more reliable)."New value: +"Rows to skip (pagination)."

addedInput schema / properties / past_company_names

Added value: +{
+  "description": "Companies the lead previously worked at (alumni targeting) — realtime only: using it forces the pricier live mode.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / personas / description

Previous value: -"Advanced: raw persona tuples [label,[titles],[secondary],[exclusions],seniority?]. Overrides job_title/job_titles."New value: +"Advanced raw persona tuples [name, functions, seniorities, prohibits, priority?] — realtime only: using it forces the pricier live mode."

changedInput schema / properties / posted_on_linkedin / description

Previous value: -"Only leads who recently posted on LinkedIn."New value: +"Only leads who recently posted on LinkedIn — realtime only: using it forces the pricier live mode."

changedInput schema / properties / seniorities / description

Previous value: -"Seniority levels (LinkedIn Sales-Nav categories, e.g. [\"Director\",\"VP\",\"Head\",\"Owner\",\"Manager\"]). Validated by the API."New value: +"Seniority at the current employer, e.g. [\"Owner\",\"CXO\",\"VP\",\"Director\",\"Manager\"]. Current position only."

addedInput schema / properties / strict

Added value: +{
+  "description": "Fields to match strictly, e.g. [\"company_locations\"].",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / timeout_ms / description

Previous value: -"Request timeout in milliseconds"New value: +"Request timeout in milliseconds."

changedInput schema / properties / without_company / description

Previous value: -"Search across all companies (filter-only). Auto-enabled when no company_id/link/name is given; this branch enforces all filters. Ignored when a company anchor is set."New value: +"DEPRECATED — accepted but ignored. No longer needed — v1 filter-only search is the default when no company anchor is set."

removedInput schema / properties / without_company / type
```
Removed value: -"boolean"
```

addedInput schema / properties / years_in_company

Added value: +{
+  "description": "Time at current company, same buckets as years_in_position — realtime only: using it forces the pricier live mode.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

addedInput schema / properties / years_in_position

Added value: +{
+  "description": "Time in current role: 1=<1y, 2=1-2y, 3=3-5y, 4=6-10y, 5=10y+ — realtime only: using it forces the pricier live mode.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Changed25 schema fields changedJul 17, 2026

addedInput schema / properties / changed_jobs

Added value: +{
+  "description": "Only leads who recently changed jobs.",
+  "type": "boolean"
+}

changedInput schema / properties / compact / description

Previous value: -"Return compact summary instead of full JSON"New value: +"Default true: return a 9-field summary per lead (name/title/company/industry/location/linkedin_url). Set false for the full raw lead object (skills, experience, etc.). Neither mode includes email — use generate_email."

addedInput schema / properties / company_headcounts

Added value: +{
+  "description": "Employer size buckets. Allowed ONLY: \"1-10\",\"11-50\",\"51-200\",\"201-500\",\"501-1000\",\"1001-5000\",\"5001-10000\",\"10 000+\" (note the space in \"10 000+\").",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / company_id / description

Previous value: -"LinkedIn company id"New value: +"Anchor to a specific LinkedIn company id (returns its employees; this branch is less deterministic and does not enforce lead_industries)."

addedInput schema / properties / company_industries

Added value: +{
+  "description": "Filter by the lead employer's industry (same taxonomy as lead_industries).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / company_link / description

Previous value: -"LinkedIn company URL"New value: +"Anchor to a specific LinkedIn company URL."

addedInput schema / properties / company_locations

Added value: +{
+  "description": "Filter by the employer HQ location (country/region names).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / company_name / description

Previous value: -"Company name"New value: +"Anchor to a specific company by name."

addedInput schema / properties / company_types

Added value: +{
+  "description": "Employer types: \"Public Company\",\"Educational\",\"Self Employed\",\"Government Agency\",\"Non Profit\",\"Self Owned\",\"Privately Held\",\"Partnership\".",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_ids

Added value: +{
+  "description": "sales_ids to exclude — pass the ids of leads already returned in prior calls to paginate/deduplicate.",
+  "items": {
+    "type": [
+      "string",
+      "number"
+    ]
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_names

Added value: +{
+  "description": "Full names to exclude from results.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_title_keywords

Added value: +{
+  "description": "Title keywords to exclude from persona matching. Defaults to [assistant, intern, junior, student, trainee]; pass [] to disable.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / functions

Added value: +{
+  "description": "Job functions (LinkedIn Sales-Nav categories, e.g. [\"Engineering\",\"Operations\",\"Marketing\",\"Sales\",\"Finance\"]). Validated by the API.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / get_max_leads

Added value: +{
+  "description": "Also report the total number of matching leads (results_count). The number of rows returned is still bounded by limit_by.",
+  "type": "boolean"
+}

changedInput schema / properties / job_title / description

Previous value: -"Job title filter (e.g., CEO, CTO, Engineer)"New value: +"Single job title (e.g., \"CEO\"). For multiple titles use job_titles."

addedInput schema / properties / job_titles

Added value: +{
+  "description": "One or more target job titles, OR-matched (e.g. [\"CEO\",\"Founder\",\"Owner\",\"President\"]). Preferred over job_title. Assistant/intern/junior/student/trainee are excluded by default; override with exclude_title_keywords.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / keywords

Added value: +{
+  "description": "Free-text keywords matched against the profile (Boolean phrases allowed).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / lead_industries / description

Previous value: -"Industry filter. Must match Generect industry names exactly (e.g. \"Information Technology and Services\", \"Financial Services\"). Invalid names are rejected by the API."New value: +"Lead personal-industry filter. Must match Generect industry names exactly (e.g. \"Financial Services\", \"IT Services and IT Consulting\"). Names are hierarchical (Financial Services includes Banking/Insurance). Invalid names are rejected (HTTP 400)."

changedInput schema / properties / limit_by / description

Previous value: -"Number of results to return"New value: +"Total leads to return this call (1–100, default 25). This is a TOTAL cap across all personas. For more, paginate with exclude_ids."

changedInput schema / properties / locations / description

Previous value: -"Location filter — country or region names, e.g. [\"United States\", \"Canada\"]"New value: +"Lead location filter — country/region names, e.g. [\"United States\",\"Canada\"]."

changedInput schema / properties / offset_by / description

Previous value: -"Offset for pagination"New value: +"Offset for pagination (note: ordering is not stable — exclude_ids is more reliable)."

addedInput schema / properties / personas

Added value: +{
+  "description": "Advanced: raw persona tuples [label,[titles],[secondary],[exclusions],seniority?]. Overrides job_title/job_titles.",
+  "type": "array"
+}

addedInput schema / properties / posted_on_linkedin

Added value: +{
+  "description": "Only leads who recently posted on LinkedIn.",
+  "type": "boolean"
+}

addedInput schema / properties / seniorities

Added value: +{
+  "description": "Seniority levels (LinkedIn Sales-Nav categories, e.g. [\"Director\",\"VP\",\"Head\",\"Owner\",\"Manager\"]). Validated by the API.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / without_company / description

Previous value: -"Search leads without filtering by companies"New value: +"Search across all companies (filter-only). Auto-enabled when no company_id/link/name is given; this branch enforces all filters. Ignored when a company anchor is set."

Changed5 schema fields changedJul 14, 2026

changedInput schema / properties / lead_industries / description

Previous value: -"Industry filter (e.g., Technology, Healthcare)"New value: +"Industry filter. Must match Generect industry names exactly (e.g. \"Information Technology and Services\", \"Financial Services\"). Invalid names are rejected by the API."

addedInput schema / properties / limit

Added value: +{
+  "description": "Alias for limit_by",
+  "type": "number"
+}

changedInput schema / properties / locations / description

Previous value: -"Location filter (e.g., San Francisco, New York)"New value: +"Location filter — country or region names, e.g. [\"United States\", \"Canada\"]"

addedInput schema / properties / offset

Added value: +{
+  "description": "Alias for offset_by",
+  "type": "number"
+}

changedInput schema / properties / without_company / description

Previous value: -"Search leads without filrest by companies"New value: +"Search leads without filtering by companies"

Changed10 schema fields changedApr 29, 2026

removedInput schema / properties / industry

Removed value: -{
-  "description": "Industry filter (e.g., Technology, Healthcare)",
-  "type": "string"
-}

addedInput schema / properties / lead_industries

Added value: +{
+  "description": "Industry filter (e.g., Technology, Healthcare)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedInput schema / properties / limit

Removed value: -{
-  "description": "Number of results to return",
-  "type": "number"
-}

addedInput schema / properties / limit_by

Added value: +{
+  "description": "Number of results to return",
+  "type": "number"
+}

removedInput schema / properties / location

Removed value: -{
-  "description": "Location filter (e.g., San Francisco, New York)",
-  "type": "string"
-}

addedInput schema / properties / locations

Added value: +{
+  "description": "Location filter (e.g., San Francisco, New York)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedInput schema / properties / max_items

Removed value: -{
-  "description": "Maximum items to include in response (local trim)",
-  "type": "number"
-}

removedInput schema / properties / offset

Removed value: -{
-  "description": "Offset for pagination",
-  "type": "number"
-}

addedInput schema / properties / offset_by

Added value: +{
+  "description": "Offset for pagination",
+  "type": "number"
+}

addedInput schema / properties / without_company

Added value: +{
+  "description": "Search leads without filrest by companies",
+  "type": "boolean"
+}

First observedFeb 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations: free thin-row quota with a 00:00 UTC reset, per-row billing (~$0.0067 / Tier 0 list), automatic escalation to realtime, the spend ceiling, 429 on a spent quota, and the fact that rows never contain email or phone. Annotations only declare readOnlyHint=false/openWorldHint=true, so this prose is doing the real behavioral work.

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

Conciseness4/5

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

Front-loaded with the cost model before any convenience guidance, and every sentence is operational rather than filler. It is a dense paragraph rather than a tight list, and the price/cost-verification advice is slightly repetitive, but nothing is wasted.

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

Completeness5/5

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

For a 43-parameter, billed search with nested company_filters and an output schema, the description covers the things an agent cannot infer: quota behavior, mode escalation billing, spend approval, pagination strategy, and which sibling tools to chain. Return-value details are left to the output schema, which is appropriate.

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?

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by explaining cross-parameter economics — 'limit_by is the price of the call' in practice, detail 'thin' guaranteeing $0, and exclude_ids as the reliable pagination handle. It does not attempt to restate the 40+ filter fields, which the schema already documents.

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?

The description opens with a specific verb+resource+scope: 'Return leads (people) matching an ICP.' It also implicitly distinguishes itself from siblings by telling the agent to run count_leads to size the audience and enrich_*/generate_email to expand rows, so an agent can tell which tool does the actual lead retrieval.

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?

Explicit routing: 'Run count_leads first — it is free and sizes the audience', 'call generate_email ... or find_phone only on the ids you keep', and 'pass detail "thin" to guarantee $0'. It also gives the pagination alternative (exclude_ids over offset) and states when full detail is worth the cost.

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

All Generect tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Search leads (free thin rows, full rows billed)

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources