search_talents_by_filters

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. Your assistant builds the filter array itself (from your request, from a previous 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

You describe the talent you need, or hand your assistant an explicit list of criteria.
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, 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 and Filter Modifiers). Several filters may share the same `filterType`.
`relatedSearchTransactionIds`	string[]	No	Array of `searchTransactionId` values from previous calls for pagination (see Pagination).

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

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

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

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 criteria as needed in a single prompt: job title + location + skills + experience + company type.

Getting Started

Tools

search_talents_by_filters

How it works

When to use this tool vs. `search_talents_by_prompt`

Input

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

​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

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