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

> Start a qualified talent search from a natural-language prompt via your AI assistant.

The `search_qualified_talents_by_prompt` tool starts a **qualified search** from a natural-language prompt. Kalent returns a `castingId` immediately. Ask the assistant to call [`get_qualified_search_result`](/mcp/get-qualified-search-result) every 10–20 seconds while `nextAction` is `wait`.

The start is a **call** with its own quota, `target` (`target.greens`, credit cap `target.maxCredits`). Within that cap Kalent analyses talents in successive waves on its own, until this call finds `target.greens` green talents, the cap is spent, or the talent pool is exhausted. Two credits are charged per judged talent, whatever the verdict, and never for a judgement started after the call's green quota was met; Kalent reserves `min(workspace balance, target.maxCredits)` when the call opens and returns unused reserved credits when each wave ends. Use [`continue_qualified_search`](/mcp/continue-qualified-search) to authorise a new budget when `nextAction` is `continue`, or to retry when it is `retry`. This tool does not accept a webhook: poll [`get_qualified_search_result`](/mcp/get-qualified-search-result) instead. Calls, waves, credits, and edge cases are explained on the [qualified search overview](/api-reference/qualified-search-overview).

The HTTP counterpart is [`POST /v1/search/talents/qualified/by-prompt`](/api-reference/search-talents-qualified-by-prompt).

## Input

| Parameter                | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`                 | string    | Yes      | Natural-language description of the talent you want Kalent to qualify. Trimmed. 1 to 4000 characters.                                                                                                                                                                                                                                                                                                                                        |
| `qualificationCriterias` | string\[] | No       | Optional qualification criteria (default `[]`). Maximum 10 items. Each string is trimmed, 1 to 300 characters. Kalent also extracts criteria from the prompt. At least one criterion is required after that merge.                                                                                                                                                                                                                           |
| `scoringLanguage`        | string    | No       | `en` or `fr`: language of `recap`, criterion `title`, and criterion `result`. Omitted: the language of the user who owns the API key, changeable at [app.kalent.ai/settings/profile](https://app.kalent.ai/settings/profile) (English when unset). Fixed for the whole search; the same request in another language is a different search with its own analysis and credits. Quotes in `references` stay in the profile's original language. |
| `target`                 | object    | No       | Quota of this call. Omitted: defaults below.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `target.greens`          | number    | No       | Green talents to find during this call, from 1 to 50. Default 10. Greens from earlier calls do not count.                                                                                                                                                                                                                                                                                                                                    |
| `target.maxCredits`      | number    | No       | Credit cap for this call, even integer from 2 to 300. Default 60 (at most 30 analysed talents).                                                                                                                                                                                                                                                                                                                                              |
| `forceNew`               | boolean   | No       | Default `false`. When `true`, starts a new qualified search even if the same prompt, criteria, and scoring language are already running.                                                                                                                                                                                                                                                                                                     |

## Response

The tool returns JSON with:

| Field       | Type    | Description                                                                |
| ----------- | ------- | -------------------------------------------------------------------------- |
| `castingId` | string  | Identifier of the qualified search                                         |
| `status`    | string  | `running`, `can_continue`, `pool_exhausted`, or `failed_retryable`         |
| `reused`    | boolean | `true` when an existing qualified search for the same request was returned |

## Errors

The tool response is marked as an error when:

* There is no MCP session
* API credits are insufficient (`Insufficient API credits: {available} available, {required} required.`)
* The prompt could not be interpreted into search filters
* No qualification criterion remains after merge
* The search times out (`The search request timed out. Please try again. (ref: …)`)