---
title: "Search Tools"
method: POST
path: "/v1/tools/search"
tags: ["Tools"]
---

# Search Tools

`POST /v1/tools/search`

## Request

- Base URL: `https://api.arcade.dev`
- URL: `https://api.arcade.dev/v1/tools/search`
- Auth: API key in header `Authorization`

Searches the caller's available tools by keyword and returns a ranked list of matches. Use this to browse what tools exist; use Select Tools to get tools for a specific task.

## Request body

- SchemasToolRecommendationRequest
  - `categories` string[]: Categories filters results to tools in any of these categories.
  - `gateway_id` string: GatewayID scopes the search to a specific gateway's tool allow list. When empty, the caller's full CATE-allowed tool universe is searched.
  - `include_static` boolean: IncludeStatic controls whether STATIC (builtin / statically configured) tools appear in results. Defaults to true when omitted.
  - `query` string, required: Query is the free-text search string. Required, non-blank.
  - `tags` string[]: Tags filters results to tools tagged with any of these labels.
  - `top_k` integer: TopK is the maximum number of results to return. Absent applies the default of 10 and is capped at 50; a present value must be positive.
  - `user_id` string: The user to search as. Required only when calling with an API key.

## Response `200`

OK

- SchemasToolRecommendationResponse
  - `results` SchemasToolRecommendationResult[]: Results are the tool matches, ordered by descending score.
    - `description` string: Description is the tool's human-readable description, pulled from Condex-side metadata when available.
    - `input_schema` unknown
    - `tool_name` string: ToolName is the versionless tool key (e.g. "Slack.SendMessage"). The gateway also renders tool names without a version suffix so callers can invoke tools without tracking toolkit version bumps.
    - `toolkit` string: Toolkit is the toolkit name the tool belongs to, when reported by Condex metadata.
    - `version` string: Version is the toolkit version string, when reported by Condex metadata.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-16** `4c694686f453`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/arcadeai/apis/arcade-api/changes/v1/tools/search/post.md)

---

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