discover_smart

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

Costs money and takes about 1-2 seconds. Use 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 when no endpoint does the named job, else no_candidates.

Inputs

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

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

{
  "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 naming it, for example Invalid input: expected string, received undefined at useCase. A token without runs.execute gets 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.