---
title: discover_smart
description: Paid tool that judges a shortlist against a plain-English use case with one small AI call, for jobs a lexical search cannot name.
---

<WorksIn />

Costs money and takes about 1-2 seconds. Use [`discover`](/mcp-tools/discover) (free, instant)
first, and reach for this only when a lexical search cannot express the job, for example "find
someone's work email from their name and company" where no endpoint's own text says "email".
Needs the `runs.execute` scope, because the judging call is billed like a run.

Two stages: the free lexical index narrows the whole catalog to a shortlist, then one
typesafe-choice run (TypeSafe's Jev model, billed per input token, about $0.00005 for a typical
shortlist, holding at most about $0.0004 before it settles to actual usage) judges that shortlist
against your `useCase` and returns the best fit plus a probability for every candidate. The
judging run appears on your normal run history and bill like any other run.

Where the server has the job-first skip on, a query the free search already resolves to a single
job with a clear top endpoint makes no paid call: `smart` comes back with `model: "job-first"`,
`runId: null`, `costUsd: 0` and `reason: "single_job_clear_winner"`.

If TypeSafe fails, times out, or answers unusably, this never errors: it returns the plain
lexical shortlist with `smart: null` and a `degraded` object naming the reason. When the free
search finds nothing, no paid call is made either: `degraded.reason` is [`no_supply_for_job`](/errors/job-refusals#no_supply_for_job) when
no endpoint does the named job, else `no_candidates`.

## Inputs

| Argument | Type | Required | Default | Limits | Meaning |
| --- | --- | --- | --- | --- | --- |
| `useCase` | string | Yes | - | 1-4000 chars | The job, described in plain English, for Jev to judge candidates against. |
| `query` | string | No | - | 1-500 chars | The lexical query that narrows the shortlist before judging. |
| `candidateLimit` | integer | No | - | 2-20 | Shortlist size passed to the judging call. |
| `filters.category` | string | No | - | - | Restrict the shortlist to a category. |
| `filters.platform` | string | No | - | - | Restrict to a platform. |
| `filters.provider` | string | No | - | - | Restrict to a provider. |
| `filters.capability` | string | No | - | - | Restrict to a job id. |
| `filters.keyless` | boolean | No | - | - | Only endpoints that need no key at all. |
| `filters.verified` | boolean | No | - | - | Only endpoints verified against a saved provider answer. |
| `filters.mock` | boolean | No | - | - | Include fixture/demo endpoints. |
| `filters.maxPriceMicros` | number | No | - | 0+ | Drop candidates priced above this. |
| `filters.hidden` | boolean | No | - | - | Include hidden endpoints. |
| `filters.includeUnavailable` | boolean | No | - | - | Include candidates with no route to run right now. |

`candidates` is ranked by Jev's `probability`, each row also carrying `lexicalRank` (where the
free search had put it). `smart` carries the winning `endpointId`, Jev's confidence, and the
`runId`/`costUsd` of the judging call.

## Example call

```json
{
  "useCase": "find a person's work email address from their full name and company domain",
  "query": "email finder",
  "candidateLimit": 5
}
```

## Example answer

Abridged: a full answer also carries `lexicalRank` and `probability` on every candidate.

```json
{
  "smart": {
    "endpointId": "icypeas-email-search",
    "confidence": 0.91,
    "runId": "run_5f0c1b2a3d4e4f56a7b8c9d0e1f2a3b4",
    "costUsd": 0.00004
  },
  "candidates": [
    {
      "endpointId": "icypeas-email-search",
      "provider": "Icypeas",
      "capability": "people.email.find",
      "probability": 0.91,
      "lexicalRank": 1
    },
    {
      "endpointId": "findymail-api-search-company",
      "provider": "Findymail",
      "capability": "people.email.find",
      "probability": 0.06,
      "lexicalRank": 3
    }
  ]
}
```

## Errors

A missing or wrong-typed `useCase` returns [`validation_error`](/errors/rest-errors#validation_error) naming it, for example
`Invalid input: expected string, received undefined at useCase`. A token without
`runs.execute` gets [`forbidden`](/errors/rest-errors#forbidden), since this tool bills a run. Beyond that, `discover_smart`
never errors on the judging step itself: a TypeSafe failure degrades to the plain lexical
shortlist with `smart: null` and `degraded` naming why. The call itself does not fail. A timed-out
judging run is cancelled and, if it had already reached the provider, still billed.

<Related />