search_talents_by_filters

The search_talents_by_filters tool searches 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. Do not use this tool for ordinary talent searches. When a user asks to find or search talents in natural language (for example “cherche des talents”, “find a senior React developer in Paris”), the assistant must call search_talents_by_prompt instead. Call search_talents_by_filters only when the user explicitly asks to search with structured Kalent filters (a filters array, filterType, isRequired, isExcluded, isExactMatch, radius, or the Kalent filter model). 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

The user explicitly asks to search with structured Kalent filters, or provides a filter list.
The AI builds a filters array, choosing the filter types, values, and modifiers (isRequired, isExcluded, isExactMatch, radius, history).
The MCP server executes the search and returns matching profiles.
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. How optional filters affect results depends on mode — see Search modes. The default is gate.

When to use this tool vs. `search_talents_by_prompt`

	`search_talents_by_prompt`	`search_talents_by_filters`
Default?	Yes — use this whenever the user asks to search or find talents in natural language	No — only if the user explicitly asks for structured Kalent filters
Input	Free-text `prompt`	Structured `filters` array
Who builds the filters	Kalent, from the prompt	Your AI assistant (visible, editable)
`isRequired: false` filters	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	See Search modes. Default is `gate`.
Best for	Everyday talent search (“cherche des talents”, “find a React developer in Paris”)	Explicit Kalent filter arrays, reusable filter specs, per-filter modifiers

Input

Parameter	Type	Required	Description
`filters`	object[]	Yes	Array of Kalent filters (see Filter Types and Filter Modifiers). Several filters may share the same `filterType`.
`relatedSearchTransactionIds`	string[]	No	Array of `searchTransactionId` values from previous calls for pagination. Maximum 300 IDs (see Pagination).
`mode`	string	No	Search engine mode: `gate` (default if omitted) or `rank`. See Search modes.
`refreshIfOlderThanMonths`	integer	No	Profiles last updated more than this many months ago are live-refreshed before being returned. Integer from `1` to `6` (default `1`). A higher value is faster but returns profiles updated less recently.

{
  "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
    }
  ]
}

Search modes

mode is optional. If omitted, the search runs in gate. The gate and rank modes work exactly as in the HTTP API: see Search modes. Accepted values for enumerated filters (languages, industries, ranges, …) are listed in Accepted filter values.

Filter Types

The AI selects from the following filter types:

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`	Year range `min-max`	One string `min-max` (both integers, both ends inclusive), lower bound ≥ 0. MCP sets no upper bound, while the HTTP API caps both bounds at 100 and requires min ≤ max. For example `5-100` (5 years or more) and `5-7`. The former buckets `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, and `30-100` remain valid.
`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: `0-1`, `1-3`, `3-5`, `5-10`, `10-15`, `15-20`, `20-30`, `30-100`
`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:

Modifier	Type	Description
`isRequired`	boolean	When `true`, the talent must match this criterion. When `false`, how the filter affects results depends on `mode`: see Search modes. 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. The estimate is capped at 10,000: a value of 10,000 means “10,000 or more”, and search and pagination can continue beyond it.
resultCompleteness — status (complete or partial), requestedCount, returnedCount and, when partial, a reason (pool_exhausted, safety_budget_reached, insufficient_ready_profiles, insufficient_credits, search_interrupted)
credits — credits consumed by this search and remaining balance
Full name, location, headline
Current job title and organization
Work experiences (company, title, location, 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. The estimate is capped at 10,000: a value of 10,000 means “10,000 or more”, and search and pagination can continue beyond it. When resultCompleteness.status is partial, the tool explains in plain language how many profiles were delivered out of the requested number and what to do next. Only ready profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. The tool accepts an optional nbToFetch (1 to 5, default 5) and keeps fetching until that many ready profiles are found or an internal page/time budget is reached. An asynchronous refresh is omitted from this response and can appear on a later call.

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
2	John Smith	Staff Engineer	Tech Inc	London, UK	Profile

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. If a LOCATION filter cannot be resolved (for example Singapore), the tool returns isError: true with Unsupported location: Singapore. Remove or rephrase that location. Retrying the same value will not succeed.

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.

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: Search with Kalent filters for 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 array accepts at most 300 IDs. The estimationCount tells you how many total matches exist, helping you decide whether to paginate further. The estimate is capped at 10,000: a value of 10,000 means “10,000 or more”, and search and pagination can continue beyond it.

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

Example Conversations

These examples assume the user asked to search with structured Kalent filters. If they only described the talent they need, use search_talents_by_prompt.

Finding engineers with specific company experience

You: Search with structured Kalent filters: software engineers who have worked at OpenAI for at least 3 years. Assistant: I’ll build a Kalent filter array 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: Use Kalent filters: talent in Paris (within 20km radius) with expertise in SEO and marketing strategies. Assistant: I’ll search with structured LOCATION and KEYWORD filters 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: Search with Kalent filters: 10+ years of experience as a UX designer who has worked for a YC startup. Assistant: I’ll build structured filters 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

Be specific about requirements

Mention specific job titles, companies, locations, and skills. The more precise you are, the better the results.

Mark nice-to-haves explicitly

All criteria are treated as mandatory by default. Use words like “ideally”, “bonus”, or “nice-to-have” for optional preferences.

Use follow-up prompts

Refine your search iteratively. Ask to narrow down by adding criteria, or broaden by relaxing constraints.

Combine multiple filters

You can combine as many filters as needed in a single call: job title + location + skills + experience + company type.

Getting Started

Embedded

Platform

search_talents_by_filters

How it works

When to use this tool vs. `search_talents_by_prompt`

Input

Search modes

Filter Types

Filter Modifiers

Response

1. Structured JSON

2. Markdown Summary Table

Errors

Credits

Non-deterministic Results

Example Conversations

Finding engineers with specific company experience

Location-based search with skills

Combining experience, role, and company type

Tips for Better Results

Be specific about requirements

Mark nice-to-haves explicitly

Use follow-up prompts

Combine multiple filters

​How it works

​When to use this tool vs. search_talents_by_prompt

​Input

​Search modes

​Filter Types

​Filter Modifiers

​Response

​1. Structured JSON

​2. Markdown Summary Table

​Errors

​Credits

​Pagination

​Non-deterministic Results

​Example Conversations

​Finding engineers with specific company experience

​Location-based search with skills

​Combining experience, role, and company type

​Tips for Better Results

Be specific about requirements

Mark nice-to-haves explicitly

Use follow-up prompts

Combine multiple filters

How it works

When to use this tool vs. `search_talents_by_prompt`

Input

Search modes

Filter Types

Filter Modifiers

Response

1. Structured JSON

2. Markdown Summary Table

Errors

Credits

Pagination

Non-deterministic Results

Example Conversations

Finding engineers with specific company experience

Location-based search with skills

Combining experience, role, and company type

Tips for Better Results