Search tools

POST/api/v1/tools:search

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. An empty connections list means the user has no account on any connection for that tool's provider; it isn't an error.

This page as markdown Tools overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Body

querystringrequired

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

identifierstring

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_kinteger

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

scalekit_client.actions.search_tools

Ranks the tools a user can call by how well they match a plain-language query. Pass identifier to get each result's connections, with a readiness_state of READY, NEEDS_CONNECTION or NEEDS_REAUTH per connection. Check it before you execute the tool.

scalekit_client.actions.search_tools(
    query: str,
    identifier: Optional[str] = None,
    top_k: Optional[int] = None,
) -> SearchToolsResponse

Parameters

querystrrequired

What the agent needs to do, in plain words or keywords

identifierOptional[str]

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_kOptional[int]

Maximum number of results

Returns SearchToolsResponse: SearchToolsResponse with tools (each a SearchedTool with name, provider, description, score and connections)

From scalekit-sdk-python 2.25.0.

Also called by scalekit_client.tools.search_tools.

scalekit.actions.searchTools

Ranks the tools a user can call by how well they match a plain-language query. Pass identifier to get each result's connections, with a readinessState per connection. Check it before you execute the tool.

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

Parameters

querystringrequired

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

identifierstring

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.

topKnumber

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

Returns Promise<SearchToolsResponse>.

From @scalekit-sdk/node 2.22.0.

Also called by scalekit.tools.searchTools.

Response 200

toolsarray of object

Tools matching the query, ordered by descending relevance score

Show 5 child attributes

connectionsarray 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.

Show 3 child attributes

connected_account_idstring

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.

connection_namestring

Name of this connection.

readiness_statestring (enum)

Whether this specific connection is usable right now for the supplied identifier, independent of every other connection listed for this provider.

TOOL_READINESS_STATE_READYTOOL_READINESS_STATE_NEEDS_CONNECTIONTOOL_READINESS_STATE_NEEDS_REAUTH

descriptionstring

Human-readable description of what the tool does

namestring

The tool's name, to pass as tool_name when you execute it.

providerstring

Provider the tool belongs to

scorenumber

Relevance score for this result. Higher is better; comparable only within a single response.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - the query is empty or exceeds the maximum length

401Authentication required - missing or invalid access token

Used in

Use built-in tools

Request

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
  }'

results = scalekit_client.actions.search_tools(
    query="send an email",
    identifier="user_123",
    top_k=5,
)

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

Response 200

1
{
2
  "tools": [
3
    {
4
      "name": "gmail_send_message",
5
      "description": "Send an email message immediately from the authenticated Gmail account. Constructs a MIME message and sends it via the Gmail API.",
6
      "provider": "GMAIL",
7
      "score": 0.87,
8
      "connections": [
9
        {
10
          "connection_name": "gmail",
11
          "connected_account_id": "ca_24834495392086178",
12
          "readiness_state": "TOOL_READINESS_STATE_READY"
13
        }
14
      ]
15
    },
16
    {
17
      "name": "slack_send_message",
18
      "description": "Send plain text to a Slack channel or DM, optionally in a thread. Returns channel and message timestamp.",
19
      "provider": "SLACK",
20
      "score": 0.61,
21
      "connections": []
22
    }
23
  ]
24
}