---
title: "Discover tools"
method: POST
path: "/tools/discover"
tags: ["Tools"]
---

# Discover tools

`POST /tools/discover`

## Request

- Base URL: `https://api.orcarouter.ai/v1`
- URL: `https://api.orcarouter.ai/v1/tools/discover`
- Auth: HTTP bearer

Search the tool catalog with a plain-language query. Free. Results
come best match first. See
[Discover & inspect](/agent-infra/tools/discover-and-inspect).

## Request body

- ToolsDiscoverRequest
  - `q` string: What the tool should do, in plain words. Up to 32 words. Empty returns the catalog listing.
  - `limit` integer
  - `category` string: A top-level category (`search`, `social-media`, …) or a two-level one (`social-media/tiktok`).
  - `min_score` number: Drop matches whose relevance score is below this.
  - `include_unavailable` boolean: Also return tools whose last health probe failed.

## Response `200`

OK

- object
  - `success` boolean
  - `data` object
    - `results` ToolCatalogEntry[]
      - `id` string
      - `provider` string
      - `provider_label` string
      - `display_name` string
      - `summary` string
      - `categories` string[]
      - `tier` 'verified' | 'bridged' | 'community'
      - `score` number: Relevance to `q`. Present only on a query.
      - `price` ToolPrice
        - `mode` 'per_call' | 'per_result' | 'per_unit'
        - `unit` string
        - `for_sale` boolean: Always `true` on discover and inspect; tools without a price are not listed.
        - `sell_usd` number: What you pay per call or per unit, all-in.
        - `est_usd_for` object
          - `units` number
          - `usd` number
      - `health` ToolHealth
        - `verdict` 'healthy' | 'stable' | 'degraded' | 'outage' | 'unknown'
        - `ok` boolean, nullable
        - `success_7d` number, nullable
        - `p50_ms` integer, nullable
        - `p50_sample_size` integer
        - `last_probe_at` integer, nullable: Unix seconds.
      - `runs_30d` integer
      - `idempotent` boolean: Repeating a call has no extra effect, so failed runs are safe to retry.
      - `version` integer

## Other responses

- `400`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).

## Changes

- **2026-11-03** `80ba8288c51d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orcarouter/apis/orcarouter-api/changes/tools/discover/post.md)

---

[API](https://skmtc.dev/orcarouter/apis/orcarouter-api.md) - [All operations](https://skmtc.dev/orcarouter/apis/orcarouter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orcarouter/apis/orcarouter-api/revisions/80ba8288c51d?raw)