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

> Search the Kalent talent database using natural language via your AI assistant.

The `search_talents` tool lets your AI assistant search the Kalent talent database using a simple natural language prompt. Describe who you are looking for in plain text — the system extracts the right search filters automatically. It returns up to **5 matching profiles** with full career details.

## How it works

1. You describe the talent you need in everyday language.
2. The MCP server converts your prompt into structured search filters using AI.
3. The search engine finds matching profiles and returns the results.
4. The AI presents a formatted table and can answer follow-up questions using the full profile data.

***

## Input

The tool accepts a single `prompt` parameter — a natural language description of the talent you are looking for.

| Parameter                     | Type      | Required | Description                                                                                               |
| ----------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `prompt`                      | string    | Yes      | Natural language description of the talent you need.                                                      |
| `relatedSearchTransactionIds` | string\[] | No       | Array of `searchTransactionId` values from previous calls for pagination (see [Pagination](#pagination)). |

### Prompt examples

* *"I need a senior React developer in Paris with 5+ years of experience"*
* *"Find me product managers who speak French and have worked at a startup"*
* *"Software engineers in London with AWS certifications and fintech experience"*
* *"UX designers with 10+ years of experience who have worked at a YC startup"*
* *"Find senior backend engineers in Paris, excluding people already in my LinkedIn network"*

<Tip>
  LinkedIn relationship filters are only used when your prompt explicitly refers
  to your own network, for example "exclude people I know" or "search within my
  connections." Accepted first-degree connections and pending invitations are
  handled as separate values.
</Tip>

***

## 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 your prompt uses a LinkedIn relationship filter 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. 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

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

***

## 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 matching profiles]*
>
> I found several 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 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 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

<CardGroup cols={2}>
  <Card title="Be specific about requirements" icon="bullseye">
    Mention specific job titles, companies, locations, and skills. The more
    precise you are, the better the results.
  </Card>

  <Card title="Use follow-up prompts" icon="arrows-rotate">
    Refine your search iteratively. Ask to narrow down by adding criteria, or
    broaden by relaxing constraints.
  </Card>

  <Card title="Combine multiple criteria" icon="layer-group">
    You can combine as many criteria as needed in a single prompt: job title +
    location + skills + experience + company type.
  </Card>

  <Card title="Watch your credits" icon="coins">
    Each search consumes credits based on the number of profiles returned. Check
    your remaining balance at any time in the billing settings.
  </Card>
</CardGroup>