Generect Live API MCP Server

Official

Overview Schema Source Related Servers Discussions(1)Admin

Search leads (free thin rows, full rows billed)

search_leads

Find people matching your ideal customer profile with free thin rows first, then pay only for the full records you keep. Size audiences for free before spending.

Instructions

Return leads (people) matching an ICP. Free by default while the account has free thin rows left today (a daily quota; detail "thin" guarantees $0). detail "full" is billable: about $0.02 per returned row (0 rows costs $0) at the Tier 0 list price. Accounts can pay a different rate: get_balance returns this account's prices, and every response reports what was actually spent in cost.amount_charged_usd. Realtime, and an automatic escalation to it, are billed per row too. count_leads sizes the audience for free first. Rows never include email or phone; generate_email (which takes the lead id) and find_phone add those for the ids you keep. Ordering is not stable, so pages are fetched by passing the ids you already have in exclude_ids rather than by offset.

Input 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

Name	Required	Description	Default
`fix`	No
`cost`	No
`mode`	No
`note`	No
`leads`	No
`detail`	No
`status`	No
`returned`	No
`companies`	No
`free_tier`	No
`test_mode`	No
`thin_note`	No
`spend_guard`	No
`results_count`	No
`next_page_args`	No
`requested_rows`	No
`escalation_note`	No
`test_mode_notice`	No
`thin_unavailable`	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.

Changed4 schema fields changedv0.12.3Oct 21, 2026
- addedOutput schema / properties / detail
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / free_tier
```
Added value: +{}
```
- addedOutput schema / properties / thin_note
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / thin_unavailable
```
Added value: +{
+  "type": "string"
+}
```

Changed18 schema fields changedv0.12.2Oct 16, 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 / 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."

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: +{}
```

Changed47 schema fields changedv0.9.0Sep 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 / changed_jobs

Added value: +{
+  "description": "Only leads who recently changed jobs — realtime only: using it forces the pricier live mode.",
+  "type": "boolean"
+}

changedInput schema / properties / compact / description

Previous value: -"Return compact summary instead of full JSON"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": {
+    "allow_unlisted_values": {
+      "description": "Escape hatch for the local vocabulary check — see the lead-side field of the same name.",
+      "type": "boolean"
+    },
+    "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"
+}

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 one company by LinkedIn numeric id."

changedInput schema / properties / company_id / type

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

addedInput schema / properties / company_industries

Added value: +{
+  "description": "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.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / company_link / description

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

addedInput schema / properties / company_locations

Added value: +{
+  "description": "HQ location of the lead's current employer.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / company_name / description

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

addedInput schema / properties / company_types

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

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"
+}

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"
+}

addedInput schema / properties / exclude_ids

Added value: +{
+  "description": "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.",
+  "items": {
+    "type": [
+      "string",
+      "number"
+    ]
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_locations

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

addedInput schema / properties / exclude_names

Added value: +{
+  "description": "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.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_title_keywords

Added value: +{
+  "description": "DEPRECATED — accepted but ignored. No v1 equivalent. Narrow job_titles instead, or filter the returned rows yourself."
+}

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"
+}

addedInput schema / properties / functions

Added value: +{
+  "description": "Job functions, e.g. [\"Sales\",\"Marketing\",\"Engineering\"] — realtime only: using it forces the pricier live mode.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / get_max_leads

Added value: +{
+  "description": "DEPRECATED — accepted but ignored. Always on now: search responses include results_count without asking."
+}

changedInput schema / properties / job_title / description

Previous value: -"Job title filter (e.g., CEO, CTO, Engineer)"New value: +"DEPRECATED alias for job_titles. Still honoured: it is merged into job_titles."

addedInput schema / properties / job_titles

Added value: +{
+  "description": "Target job titles, OR-matched (e.g. [\"CEO\",\"Founder\",\"Owner\"]). A lead needs to match only one.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / keywords

Added value: +{
+  "description": "Free-text keywords across headline/summary/skills — realtime only: using it forces the pricier live mode.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / lead_industries / description

Previous value: -"Industry filter (e.g., Technology, Healthcare)"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"
```

addedInput schema / properties / limit

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

changedInput schema / properties / limit_by / description

Previous value: -"Number of results to return"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: -"Location filter (e.g., San Francisco, New York)"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"
+}

addedInput schema / properties / offset

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

changedInput schema / properties / offset_by / description

Previous value: -"Offset for pagination"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"
+}

addedInput schema / properties / personas

Added value: +{
+  "description": "Advanced raw persona tuples [name, functions, seniorities, prohibits, priority?] — realtime only: using it forces the pricier live mode.",
+  "type": "array"
+}

addedInput schema / properties / posted_on_linkedin

Added value: +{
+  "description": "Only leads who recently posted on LinkedIn — realtime only: using it forces the pricier live mode.",
+  "type": "boolean"
+}

addedInput schema / properties / seniorities

Added value: +{
+  "description": "Seniority at the current employer, e.g. [\"Owner\",\"CXO\",\"VP\",\"Director\",\"Manager\"]. Current position only.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

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 leads without filrest by companies"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"
+}

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"
+}

First observedv0.1.0May 26, 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 (readOnly false, openWorld true, destructive false) by disclosing pricing (~$0.02/row, 0 rows costs $0), the daily free thin-row quota with 00:00 UTC reset, a 429 on a spent thin quota, the per-call spend ceiling and confirm_spend refusal threshold, realtime escalation cost, and that every response reports cost.amount_charged_usd. It also warns that ordering is unstable — behavior no annotation could convey.

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 on what is returned and what it costs, then guidance, then the data caveat — a sensible priority order. Slightly dense in the middle (realtime/escalation billing sentence is compressed and needs a second read), but no sentence is filler.

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 search tool with an output schema and full annotation coverage, the description covers the things the schema cannot: cost model, free-tier quota behavior, escalation, contact-field gaps and pagination strategy. Nothing needed to call it safely or correctly is missing.

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 schema carries mode/detail/limit_by semantics and the baseline is 3. The description still adds rate context the schema lacks — Tier 0 list price vs the account's actual rate via get_balance — plus the pagination rationale behind exclude_ids and the missing-email/phone constraint on returned rows.

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?

States a specific verb and resource — 'Return leads (people) matching an ICP' — and the title immediately frames the free-vs-billed distinction that separates it from count_leads, enrich_lead and search_companies. An agent can tell what it produces (lead rows, no email/phone) 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.

Usage Guidelines5/5

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

Explicitly routes the agent: 'count_leads sizes the audience for free first', 'Browse thin, then spend only on the rows you keep', generate_email/find_phone for contacts on kept ids, and exclude_ids instead of offset for paging. Both the cheap path and the alternatives are named with the condition that selects them.

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