---
title: "Select Tools"
method: POST
path: "/v1/tools/select"
tags: ["Tools"]
---

# Select Tools

`POST /v1/tools/select`

## Request

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

Selects the tools best suited to each of the given tasks, returning per-task suggestions with their input schemas. Pass the returned query_id to Execute Tool so the execution is correlated with the selection that surfaced the tool.

## Request body

- SchemasToolSelectRequest
  - `categories` string[]: Categories filters candidates to tools in any of these categories.
  - `context` string: Context is optional supplementary text (e.g. conversation history) sent to Condex via its dedicated context field. Condex keeps it out of the BM25 text leg; it informs the rerank stage (and embeddings only when Condex runs with SELECT_INCLUDE_EMBED_CONTEXT=true).
  - `gateway_id` string: GatewayID scopes selection to a specific gateway's tool allow list. When empty, the caller's full CATE-allowed tool universe is considered.
  - `include_static` boolean: IncludeStatic controls whether STATIC (builtin / statically configured) tools appear as candidates. Defaults to true when omitted.
  - `tags` string[]: Tags filters candidates to tools tagged with any of these labels.
  - `tasks` string[], required: Tasks is the list of task descriptions to select tools for. Each task is sent to Condex individually and produces its own TaskSelectionResult. Must contain at least one entry, and no entry may be blank.
  - `top_k` integer: TopK is the maximum number of suggestions to return per task. Absent applies the default of 5 and is capped at 20; a present value must be positive.
  - `user_id` string: The user to select tools as. Required only when calling with an API key.

## Response `200`

OK

- SchemasToolSelectResponse
  - `query_id` string: QueryID is the Condex-assigned identifier for this selection query. Taken from the first non-empty QueryID returned across tasks.
  - `results` SchemasTaskSelectionResult[]: Results is one TaskSelectionResult per input task, in the order the tasks were submitted.
    - `suggestions` SchemasToolRecommendationResult[]: Suggestions is the ordered list of suggested tools for this task.
      - `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.
    - `task` string: Task is the task string from the request, echoed back for correlation.

## 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/select/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)