SCscalekit
Tool Calling

Search tools by query

Changed on

Ranks tools in the environment against a natural-language query and returns the best matches, drawn from every connection enabled in the environment. Pass identifier to also annotate each result with per-connection readiness (TOOL_READINESS_STATE_READY, TOOL_READINESS_STATE_NEEDS_CONNECTION, TOOL_READINESS_STATE_NEEDS_REAUTH) for that identifier, so you can gate execution on the right auth step before calling ExecuteTool. An empty connections array means the identifier has no connection at all for that tool's provider -- not an error, and distinct from TOOL_READINESS_STATE_NEEDS_CONNECTION (a connected account exists but is inactive).

post/api/v1/tools:search

Request

Request body

identifierstring

Optional connected-account identifier (e.g. the end user's email or ID). When set, each result is annotated with a readiness state for this identifier's connections. When omitted, results are ranked without readiness annotation.

querystring required

Natural-language query or keywords describing the job to be done. Ranked against tool names, descriptions, and providers. 1-256 characters.

top_kinteger

Maximum number of ranked results to return. Defaults to 10, capped at 50.

Example request

{
  "identifier": "user@example.com",
  "query": "send a message to a slack channel",
  "top_k": 10
}

Response

Ranked tools matching the query, with per-identifier readiness when an identifier is supplied

Example response

{
  "tools": [
    {
      "connections": [
        {
          "connected_account_id": "ca_123",
          "connection_name": "Acme Slack"
        }
      ],
      "description": "Send a message to a Slack channel or user",
      "name": "slack_send_message",
      "provider": "SLACK",
      "score": 0.82
    }
  ]
}

Changes