> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# search_talents_by_filters
> Search the Kalent talent database with structured Kalent filters via your AI assistant.
The `search_talents_by_filters` tool lets your AI assistant search the Kalent talent database with **structured Kalent filters** — the same filter model used by the Kalent app and by the [`POST /v1/search/talents`](/api-reference/search-talents) API. Your assistant builds the filter array itself (from your request, from a previous [`search_talents_by_prompt`](/mcp/search-talents-by-prompt) call, or from a skill you maintain), so you keep precise control over every criterion. It returns up to **5 matching profiles** with full career details.
This tool was previously available in development environments as
`search_talents_with_filters`. It is now exposed to every MCP client under the
name `search_talents_by_filters`.
## How it works
1. You describe the talent you need, or hand your assistant an explicit list of criteria.
2. The AI builds a `filters` array, choosing the filter types, values, and modifiers (`isRequired`, `isExcluded`, `isExactMatch`, `radius`, `history`).
3. The MCP server executes the search and returns matching profiles.
4. The AI presents a formatted table and can answer follow-up questions using the full profile data.
Every criterion you mention is treated as a **requirement** by default
(`isRequired: true`). If you want a criterion to be a nice-to-have rather than
mandatory, say so explicitly (e.g., *"ideally with experience in fintech"* or
*"bonus if they speak Spanish"*) — the AI then sets `isRequired: false` on
that filter, and it becomes a **preference**: profiles that do not match it
can still be returned, and matching profiles come first.
## When to use this tool vs. `search_talents_by_prompt`
| | `search_talents_by_filters` | `search_talents_by_prompt` |
| --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input | Structured `filters` array | Free-text `prompt` |
| Who builds the filters | Your AI assistant (visible, editable) | Kalent, from the prompt |
| `isRequired: false` filters | Preferences — non-matching profiles can still be returned, matching ones first | Not applicable — every kind of criterion in the prompt is required; with several values of one kind, matching one is enough unless the prompt says they are all mandatory |
| Best for | Precise control, reusable searches, skills, exclusions, radius, exact matches | Quick exploratory searches in plain language |
***
## Input
| Parameter | Type | Required | Description |
| ----------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters` | object\[] | Yes | Array of Kalent filters (see [Filter Types](#filter-types) and [Filter Modifiers](#filter-modifiers)). Several filters may share the same `filterType`. |
| `relatedSearchTransactionIds` | string\[] | No | Array of `searchTransactionId` values from previous calls for pagination (see [Pagination](#pagination)). |
```json theme={null}
{
"filters": [
{
"filterType": "JOB_TITLE",
"value": "Product Designer",
"isRequired": true,
"isExcluded": false,
"isExactMatch": false,
"history": "CURRENT"
},
{
"filterType": "LOCATION",
"value": "Paris",
"isRequired": true,
"isExcluded": false,
"isExactMatch": false,
"radius": 30
},
{
"filterType": "KEYWORD",
"value": "Figma",
"isRequired": false,
"isExcluded": false,
"isExactMatch": false
}
]
}
```
Accepted values for enumerated filters (languages, industries, ranges, …) are listed in [Accepted filter values](/api-reference/accepted-filter-values).
***
## Filter Types
The AI selects from the following filter types based on your prompt:
| Filter type | Value format | Description |
| --------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JOB_TITLE` | Free text | Job title or role (e.g., "Product Designer", "Software Engineer") |
| `LOCATION` | City or country | Geographic location with optional radius in km |
| `YEARS_OF_EXPERIENCE` | Range bucket | Professional experience: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100` |
| `SKILL` | Free text | Dedicated skills list on a profile (often incomplete). Prefer `KEYWORD` for a tech or competency. Retry as `KEYWORD` if this returns no results. |
| `KEYWORD` | Free text | Full profile text (headline, summary, experience). Prefer this for a tech or competency (e.g., React, SEO, Figma). |
| `LANGUAGE` | Lowercase name | Spoken language (e.g., "french", "english", "mandarin") |
| `LANGUAGE_PROFICIENCY` | Level string | Language proficiency level |
| `COMPANY_NAME` | Free text | Current or past employer |
| `COMPANY_SIZE` | Range bucket | Company headcount: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` |
| `COMPANY_INDUSTRY` | Industry string | Employer industry sector (e.g., "computer software", "financial services") |
| `EDUCATION_DEGREE` | Degree level | Highest degree: `bachelors`, `masters`, `doctorates` |
| `EDUCATION_SCHOOL_NAME` | Free text | School or university name |
| `CERTIFICATION_NAME` | Free text | Professional certification (e.g., "AWS Certified", "PMP") |
| `SENIORITY` | Contract type | Currently supports: `Freelance` |
| `DURATION_IN_JOB` | Range bucket | Tenure in current/last role (same buckets as years of experience) |
| `GRADUATION_YEAR` | Four-digit year | Graduation year (e.g., "2020") |
| `LINKEDIN_RELATIONS_DEGREE` | `1st degree` or `invited` | Relationship to your connected LinkedIn account. `1st degree` means accepted first-degree connections only; `invited` means pending invitations only. |
***
## Filter Modifiers
Each filter supports the following modifiers that the AI sets based on your prompt:
| Modifier | Type | Description |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired` | boolean | When `true`, the talent **must** match this criterion. When `false`, the criterion is a preference: non-matching talents can still be returned, matching ones first. Set to `true` by default for every filter. |
| `isExcluded` | boolean | When `true`, talents matching this filter are **excluded** from results. |
| `isExactMatch` | boolean | When `true`, the value must match exactly (no fuzzy matching). |
| `radius` | number | Search radius in **kilometers**. Only applies to `LOCATION` filters. |
| `history` | string | Temporal scope: `CURRENT`, `PAST`, or `CURRENT_AND_PAST`. Only applies to `JOB_TITLE` and `COMPANY_NAME`. |
**About location radius:** The radius is always in **kilometers**. You can
mention miles in your prompt — the AI automatically handles the conversion.
For example, "within 30 miles of London" will be converted to approximately 48
km.
**Prefer `KEYWORD` for a technology or competency.** `SKILL` only matches the
dedicated skills list on a profile, which many people leave empty. `KEYWORD`
searches the whole profile. If a search that uses `SKILL` returns
`estimationCount: 0` or no talents, call the tool again with the same value as
`KEYWORD`. Do not add both on the first call.
**About LinkedIn relationship filters:** Use this filter only when the request
explicitly refers to your own LinkedIn network, such as "exclude people I
know" or "search within my connections." The values `1st degree` and `invited`
are distinct: accepted first-degree connections do not include pending
invitations.
***
## Response
Each search returns two content blocks:
### 1. Structured JSON
Complete profile data for each matching talent, including:
* `searchTransactionId` — unique identifier for this search (used for pagination)
* `estimationCount` — the total estimated number of talents matching the filters in the database, not just the ones returned in this batch
* `pendingRefreshCount` — number of matching profiles in the current batch that are currently being updated and were excluded from this response; retry shortly to retrieve them once ready
* `credits` — credits consumed by this search and remaining balance
* Full name, location, headline
* Current job title and organization
* Work experiences (company, title, dates, description)
* Education (school, degree, major, dates)
* Skills
* Languages and proficiency levels
* Professional certifications
* LinkedIn profile URL
The AI uses this data to answer follow-up questions, compare candidates, or refine searches. The `searchTransactionId` is used internally for pagination (see below). The `estimationCount` helps convey how large the overall talent pool is for the given criteria. When `pendingRefreshCount` is greater than zero, the tool explains that some matching profiles are still being updated and a retry is recommended.
Only **ready** profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. Profiles currently being updated asynchronously are excluded from the current response.
### 2. Markdown Summary Table
A formatted table displayed directly in the conversation:
| # | Name | Job Title | Company | Location | LinkedIn |
| - | ------------ | ------------------------ | --------- | ------------- | -------------------------------------- |
| 1 | Marie Dupont | Senior Software Engineer | Acme Corp | Paris, France | [Profile](https://linkedin.com/in/...) |
| 2 | John Smith | Staff Engineer | Tech Inc | London, UK | [Profile](https://linkedin.com/in/...) |
***
## Errors
If the search engine times out, the tool returns `isError: true` with a message asking you to try again and a `ref:` line containing the request `debugTrackingCode` for support.
If a LinkedIn relationship filter is used but no LinkedIn account is connected, the tool returns an error asking you to connect LinkedIn in Kalent settings before filtering by your network.
## Credits
Each search consumes **API search credits**. The number of credits consumed corresponds to the number of profiles returned (up to 5 per search). The response includes a `credits` object showing how many credits were used and how many remain.
If you run out of credits, the tool will return an error prompting you to purchase more at [https://app.kalent.ai/settings/billing](https://app.kalent.ai/settings/billing).
***
## Pagination
When you ask for more results, the AI automatically handles pagination by passing previous `searchTransactionId` values via the `relatedSearchTransactionIds` parameter. `relatedSearchTransactionIds` is an array of `searchTransactionId` strings from previous `search_talents_by_filters` calls — talents already returned in those earlier searches are excluded from the new results, so you always see fresh profiles.
> **You:** Find me React developers in Paris.
>
> *\[5 results displayed — estimationCount: 120]*
>
> **You:** Show me more.
>
> *\[5 new, different results displayed — no duplicates from the first batch]*
The AI collects `searchTransactionId` values from each response and passes them in subsequent requests so you never see the same talent twice. The `estimationCount` tells you how many total matches exist, helping you decide whether to paginate further.
***
## Non-deterministic Results
Search results may vary between identical requests. This is expected and by design:
* **Real-time profile refresh** — talent profiles are enriched and updated live during each search. A profile that didn't match before may match now after a refresh (and vice versa).
* **AI-powered scoring** — result ranking uses AI models whose outputs can differ slightly between calls.
* **Continuous indexing** — new talents are added and existing profiles are updated from external sources on an ongoing basis.
The pagination mechanism guarantees you will **never see the same talent twice** within a paginated session. However, the overall set of matching talents may shift between calls. This is inherent to a live, AI-augmented search engine and does not affect result accuracy — every returned talent genuinely matches your criteria at the time of the request.
Read more in the [Non-deterministic Results](/mcp/non-deterministic-results) guide.
***
## Example Conversations
### Finding engineers with specific company experience
> **You:** Find software engineers who have worked at OpenAI for at least 3 years.
>
> **Assistant:** I'll search for software engineers with OpenAI experience and at least 3 years in the role.
>
> *\[Results displayed as a table with 5 matching profiles]*
>
> I found 5 software engineers who match your criteria. Would you like me to look into any of these profiles in more detail, or would you like to refine the search?
### Location-based search with skills
> **You:** I need to find talent in Paris (within 20km radius) with expertise in SEO and marketing strategies.
>
> **Assistant:** Let me search for marketing professionals near Paris with SEO expertise.
>
> *\[Results displayed]*
>
> Here are 5 professionals in the Paris area with SEO and marketing strategy skills. Several of them also have experience in content marketing and digital analytics.
### Combining experience, role, and company type
> **You:** Find talent with 10+ years of experience as a UX designer who has worked for a YC startup.
>
> **Assistant:** I'll search for senior UX designers with Y Combinator startup experience.
>
> *\[Results displayed]*
>
> I found 5 UX designers with 10+ years of experience and ties to Y Combinator startups. Want me to narrow down by location or specific skills?
***
## Tips for Better Results
Mention specific job titles, companies, locations, and skills. The more
precise you are, the better the results.
All criteria are treated as mandatory by default. Use words like "ideally",
"bonus", or "nice-to-have" for optional preferences.
Refine your search iteratively. Ask to narrow down by adding criteria, or
broaden by relaxing constraints.
You can combine as many criteria as needed in a single prompt: job title +
location + skills + experience + company type.