> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useagents.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Search

> Search the UseAgents tool directory with a natural-language query and get ranked tool results.

Search the UseAgents tool directory using natural language. The endpoint returns ranked tools with metadata such as descriptions, supported languages, frameworks, and categories.

<Info>
  This endpoint requires authentication. Include your API key in the
  `Authorization` header.
</Info>

## Endpoint

```text theme={null}
GET /tools/search
```

Base URL:

```text theme={null}
https://api.useagents.site
```

## Query parameters

| Parameter | Type   | Required | Description                                                                                        |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `q`       | string | Yes      | Natural-language query. Searches across tool names, descriptions, tags, languages, and categories. |

## Response

The response contains a `results` array. Each result includes:

| Field              | Type           | Description                                    |
| ------------------ | -------------- | ---------------------------------------------- |
| `id`               | string         | Unique identifier for the tool                 |
| `name`             | string         | Tool name                                      |
| `description`      | string         | Full description                               |
| `shortDescription` | string         | Brief summary                                  |
| `languages`        | string\[]      | Supported languages (for example `TypeScript`) |
| `frameworks`       | string\[]      | Supported frameworks                           |
| `categories`       | string\[]      | Categories such as `Authentication` or `CLI`   |
| `slug`             | string         | URL-friendly identifier for the tool           |
| `updatedAt`        | string \| null | ISO timestamp when the tool was last updated   |

## Example request

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.useagents.site/tools/search?q=authentication%20library%20for%20Node.js"
```

## Example response

```json theme={null}
{
  "results": [
    {
      "id": "tool_abc123",
      "name": "Example Auth SDK",
      "description": "A TypeScript authentication library for Node.js applications.",
      "shortDescription": "Auth SDK for Node.js",
      "languages": ["TypeScript", "JavaScript"],
      "frameworks": ["Express", "Next.js"],
      "categories": ["Authentication", "SDK"],
      "slug": "example-auth-sdk",
      "updatedAt": "2026-07-23T12:00:00.000Z"
    }
  ]
}
```

## Query writing tips

* Describe the job to be done, not just a package name.
* Include the language, framework, or platform when it matters.
* Include constraints such as `CLI`, `self-hosted`, or `webhooks` if they affect tool choice.

## Use this endpoint when

* Discover tools by natural-language query
* Get accurate metadata for ranking, filtering, or selection
* Build tool discovery UIs or agent integrations