> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/discover

# POST /v1/discover

> Find the right tool for a task in a few words, best first, with a verdict; or every enabled tool with the jobs they serve. Free.

```text
POST https://api.parel.si/v1/discover
```

Any valid key. Free.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | no | What you need, in a few words: `"work email of a person"`, `"competitor ads"`, `"who is hiring"`, `"youtube transcript"`. The words are matched one by one, so their order does not matter. Without it, every enabled tool. |
| `job` | string | no | A job id from `jobs[]` (`"work_email"`, `"instagram"`): only that job's tools. With `query`, the best of that job. |
| `limit` | integer | no | How many tools a `query` returns, 1 to 50. Default 8. |

```bash
curl https://api.parel.si/v1/discover \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"work email of a person"}'
```

## How a query is matched

Each word of the query is scored on its own, by where it appears in a tool and how rare it is across all tools. A tool's name, its title and the other words people use for it count most; then its one-line summary, when to pick it over a look-alike, and what it returns; then its job; then its example prompt and description. Plurals and tenses are folded together ("emails", "email"), a few synonyms are read as one word ("twitter" and "x", "hiring" and "vacancies"), and some Hinglish works ("kisi company ka email", "naukri dhundo"). A tool named exactly (`find_email`) comes first.

## Response

`ok: true` and `tools[]`. Disabled tools are never listed.

**With a `query`:** at most `limit` tools, best first, plus:

| Field | Type | Description |
|---|---|---|
| `query` | string | The query as received |
| `verdict` | string | `match`: the first tool fits. `nearest`: only something close was found; check before running. `none`: nothing fits, and `tools` is empty |
| `hint` | string | On `nearest` and `none`: how to ask differently |
| `jobs` | array | On `none`: the jobs, to browse with `job` instead |

**Without a `query`:** every enabled tool (or every tool of `job`), as before, plus `jobs[]`: each job's `job` id, `label`, `tools` (how many) and `examples` (up to three names).

Each row of `tools[]`:

| Field | Type | Description |
|---|---|---|
| `name` | string | The tool name to send to [`POST /v1/run`](https://parel.si/docs/api/run.md) |
| `summary` | string | One line |
| `description` | string | The paragraph an agent reads: what it returns, what it will not do, which sibling to use, what drives the cost, India notes, then today's price and the ₹0 rule |
| `price` | string | The price in a sentence, computed at today's rate: `"~₹2.80 per successful result; a miss is free"` |
| `estimated_cost_paise`, `estimated_cost` | integer, string | The estimated charge for one call at today's rate; for a tool priced per result or by mode, its dearest case |
| `async` | boolean | A slow job |
| `free_when_no_result` | boolean | An empty answer is ₹0 |
| `confirm_required` | boolean | Running it needs `confirm: true` whatever the input |
| `job` | string | The job the tool serves (`work_email`); null for a tool not yet given one |
| `pick_when` | string | Only on look-alike tools: when to pick this one, and which sibling serves the other needs |
| `score` | number | With a `query`: how well it matched. Only the order means anything |

The price is computed by the same formula and exchange rate that settle the call. For the input schema, notes and an example input, read [`GET /v1/tools/:id`](https://parel.si/docs/api/tool.md). An unknown `job` answers `400` with `error: "unknown_job"` and the list of jobs, for ₹0.

Computed in-process from the seeded catalogue on 2026-11-17 with `{"query": "work email of a person"}`, the first two rows shown, descriptions shortened here:

```json
{
  "ok": true,
  "query": "work email of a person",
  "verdict": "match",
  "tools": [
    {
      "name": "find_email",
      "summary": "One person's work email from name + company domain, with confidence; a miss is free.",
      "description": "One person's work email from their name and company: give domain (preferred) or company, plus full_name or first_name and last_name; or linkedin_handle alone. Returns the best-guess address with a confidence score (0 to…",
      "price": "~₹2.77 per successful result; a miss is free",
      "estimated_cost_paise": 277,
      "estimated_cost": "₹2.77",
      "async": false,
      "free_when_no_result": true,
      "confirm_required": false,
      "job": "work_email",
      "pick_when": "One known person at one company. Everyone at a company: domain_search; the format only: get_email_pattern.",
      "score": 41.19
    },
    {
      "name": "enrich_person",
      "summary": "One known person from a work email, LinkedIn URL or name and company: title, employer, seniority, location, career history.",
      "description": "One known person from a linkedin_url, a work email, or a name with an employer: data.person with name, title, headline, seniority, functions, city and country, employment_history[] and organization (name, domain, indust…",
      "price": "~₹2.94 per successful result; a miss is free",
      "estimated_cost_paise": 294,
      "estimated_cost": "₹2.94",
      "async": false,
      "free_when_no_result": true,
      "confirm_required": false,
      "job": "person_profile",
      "pick_when": "One known person from an email, profile link or name and company; LinkedIn's own profile: get_linkedin_profile.",
      "score": 35.01
    }
  ]
}
```

## Related

- [`GET /v1/tools`](https://parel.si/docs/api/tools.md): the same answers as a `GET`, with `query`, `job` and `limit` as parameters.
- Over MCP: `discover_tools`, which with no query answers with the jobs instead of every tool, and puts the input schema in the first three rows of a match. [MCP reference](https://parel.si/docs/mcp.md#discover_tools).
