> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Search tools (beta)

`POST /api/v1/tools:search`

This endpoint is in beta. Its request and response may change.

Ranks the tools in your environment against a plain-language query, such as `send an email`, and returns the best matches from every connection. Pass `identifier` to see, for each result, whether that user can call it now: each entry in `connections` has a `readiness_state` of `TOOL_READINESS_STATE_READY`, `TOOL_READINESS_STATE_NEEDS_CONNECTION` (the account exists but isn't active) or `TOOL_READINESS_STATE_NEEDS_REAUTH`. Check it before you [execute the tool](https://docs.scalekit.com/agentkit/reference/tools/execute-a-tool/). An empty `connections` list means the user has no account on any connection for that tool's provider; it isn't an error.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Natural-language query or keywords describing the job to be done. Ranked against tool names, descriptions, and providers. 1-256 characters. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `top_k` | integer | No | Maximum number of ranked results to return. Defaults to 10, capped at 50. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `tools` | array of object | Tools matching the query, ordered by descending relevance score. |
| `tools.connections` | array of object | The connections for this tool's provider where the user has a connected account, each with its own `readiness_state`. Returned only when the request has `identifier`. Empty when the user has no account on any of them. More than one entry means the user has accounts on several connections, such as two Slack workspaces. |
| `tools.connections.connected_account_id` | string | The user's connected account on this connection, whatever its readiness. Pass it to Execute a tool only when `readiness_state` is `TOOL_READINESS_STATE_READY`. |
| `tools.connections.connection_name` | string | Name of this connection. |
| `tools.connections.readiness_state` | string (enum) | Whether this specific connection is usable right now for the supplied identifier, independent of every other connection listed for this provider. One of: `TOOL_READINESS_STATE_READY`, `TOOL_READINESS_STATE_NEEDS_CONNECTION`, `TOOL_READINESS_STATE_NEEDS_REAUTH`. |
| `tools.description` | string | Human-readable description of what the tool does. |
| `tools.name` | string | The tool's name, to pass as `tool_name` when you [execute it](https://docs.scalekit.com/agentkit/reference/tools/execute-a-tool/). |
| `tools.provider` | string | Provider the tool belongs to. |
| `tools.score` | number | Relevance score for this result. Higher is better; comparable only within a single response. |

**Errors**

- `400`: Invalid request - the query is empty or exceeds the maximum length
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/tools:search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "send an email",
    "identifier": "user_123",
    "top_k": 5
  }'
```

**Response**

```json
{
  "tools": [
    {
      "name": "gmail_send_message",
      "description": "Send an email message immediately from the authenticated Gmail account. Constructs a MIME message and sends it via the Gmail API.",
      "provider": "GMAIL",
      "score": 0.87,
      "connections": [
        {
          "connection_name": "gmail",
          "connected_account_id": "ca_24834495392086178",
          "readiness_state": "TOOL_READINESS_STATE_READY"
        }
      ]
    },
    {
      "name": "slack_send_message",
      "description": "Send plain text to a Slack channel or DM, optionally in a thread. Returns channel and message timestamp.",
      "provider": "SLACK",
      "score": 0.61,
      "connections": []
    }
  ]
}
```

**Python SDK:** `scalekit_client.tools.search_tools`

Ranks the tools a user can call by how well they match a plain-language query. Each result's `score` is a relevance score where higher is better; it is only comparable within the results of a single response, not across separate calls. `connections` on each result is populated only when `identifier` is set: an empty list means the identifier has no connection at all for that tool's provider (not an error, and different from `NEEDS_CONNECTION`, which means a connected account row exists but is inactive); more than one entry means the identifier has accounts on multiple connections for that provider (for example, two Slack workspaces) -- inspect each entry's own `readiness_state` rather than assuming one answer for the whole tool.

```python
scalekit_client.tools.search_tools(
    query: str,
    identifier: Optional[str] = None,
    top_k: Optional[int] = None,
) -> Tuple[SearchToolsResponse, grpc.Call]
```

Example:

```python
results, _ = scalekit_client.tools.search_tools(
    query="send an email",
    identifier="user_123",
    top_k=5,
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `str` | Yes | Natural-language query or keywords describing the job to be done |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `top_k` | `Optional[int]` | No | Maximum number of ranked results to return (default 10, capped at 50) |

Returns `Tuple[SearchToolsResponse, grpc.Call]`: The response and the gRPC call. Unpack it as `results, _ = ...`.

**Node.js SDK:** `scalekit.tools.searchTools`

Searches tools ranked by relevance to a natural-language query — the job to be done, not an exact tool name. Each result's `score` is a relevance score where higher is better; it is only comparable within the results of a single response, not across separate calls. Pass `identifier` to also get per-connection readiness (usable now, needs a new connection, or needs re-auth) on each result's `connections`. `connections` is populated only when `identifier` is set: an empty array means the identifier has no connection at all for that tool's provider (not an error, and different from `NEEDS_CONNECTION`, which means a connected-account row exists but is inactive); more than one entry means the identifier has accounts on multiple connections for that provider (for example, two Slack workspaces) — inspect each entry's own `readinessState` rather than assuming one answer for the whole tool.

```ts
scalekit.tools.searchTools(
  query: string,
  options?: {
    identifier?: string;
    topK?: number;
  },
): Promise<SearchToolsResponse>
```

Example:

```ts
const result = await scalekit.tools.searchTools("send an email", {
  identifier: "user_123",
  topK: 5,
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | Yes | Natural-language query or keywords describing the job to be done. 1-256 characters. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `topK` | `number` | No | Maximum number of ranked results to return. Defaults to 10, capped at 50. |

Returns `Promise<SearchToolsResponse>`.

**Used in**

- [Use built-in tools](https://docs.scalekit.com/agentkit/tools/scalekit-optimized-tools/)


Part of [Tools](https://docs.scalekit.com/agentkit/reference/tools/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |