List a user's scoped tools Beta

GET/api/v1/tools/scoped

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

Tools already bound to one connected-account identifier. Use this when you need the list a user or agent is authorized to call (the list you pass to an LLM). identifier is required, and so is at least one filter.* field (provider, tool name or connection name): without one the API returns INVALID_ARGUMENT.

This page as markdown Tools overview

Authorization

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

Query parameters

identifierstringrequired

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.

filter.connection_namesarray of string

Filter by one or more connection names

filter.providersarray of string

Filter by one or more tool providers

filter.tool_namesarray of string

Filter by one or more tool names

page_sizeinteger

Maximum number of tools to return per page

page_tokenstring

Token from a previous response for pagination

scalekit_client.tools.list_scoped_tools

Lists the tools a user can call, narrowed by the filter.

scalekit_client.tools.list_scoped_tools(
    identifier: str,
    filter: Optional[ScopedToolFilter] = None,
    page_size: Optional[int] = None,
    page_token: Optional[str] = None,
) -> Tuple[ListScopedToolsResponse, grpc.Call]

Parameters

identifierstrrequired

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.

filterOptional[ScopedToolFilter]required

Filter parameters for scoped tools

page_sizeOptional[int]

Maximum number of tools to return per page

page_tokenOptional[str]

Token from a previous response for pagination

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

From scalekit-sdk-python 2.19.1.

scalekit.tools.listScopedTools

Lists tools that are scoped to a specific connected account identifier.

scalekit.tools.listScopedTools(
  identifier: string,
  options: {
    filter: MessageInitShape<typeof ScopedToolFilterSchema>;
    pageSize?: number;
    pageToken?: string;
  },
): Promise<ListScopedToolsResponse>

Parameters

identifierstringrequired

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.

filterMessageInitShape<typeof ScopedToolFilterSchema>required

Filter configuration for scoped tools (providers, tool names, connection names). Required.

pageSizenumber

Maximum number of tools to return per page.

pageTokenstring

Token from a previous listScopedTools response for pagination.

Returns Promise<ListScopedToolsResponse>.

From @scalekit-sdk/node 2.18.0.

Response 200

next_page_tokenstring

Token for fetching the next page of tools

prev_page_tokenstring

Token for fetching the previous page of tools

toolsarray of object

List of tools scoped to the given connected account identifier

Show 3 child attributes

connected_account_idstring

ID of the connected account for this scoped tool

identifierstring

Your app's ID for the user, the value passed when the account was created.

toolobject

The underlying tool definition

Show 7 child attributes

definitionobject

Tool definition in structured format

idstring

Unique ID of the tool. Immutable and read-only.

is_defaultboolean

Marks this tool as the default version for the combination. Read-only.

metadataobject

Additional metadata about the tool

providerstring

Provider name (e.g. GOOGLE). Read-only.

tagsarray of string

Tags for categorization or filtering

updated_atstring

Timestamp when the tool was last updated. Read-only.

total_sizeinteger

Total number of tools matching the query

Errors

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

400Invalid request - missing identifier or malformed filter/pagination parameters

401Authentication required - missing or invalid access token

Used in

Request

curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/tools/scoped" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "identifier=user_123" \
  --data-urlencode "filter.connection_names=gmail" \
  --data-urlencode "page_size=2"

page, _ = scalekit_client.tools.list_scoped_tools(
    identifier="user_123",
    filter={"connection_names": ["gmail"]},
    page_size=2,
)

const result = await scalekit.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["gmail"] },
  pageSize: 2,
});

Response 200

1
{
2
  "tools": [
3
    {
4
      "connected_account_id": "ca_24834495392086178",
5
      "identifier": "user_123",
6
      "tool": {
7
        "id": "tol_86147403291582051",
8
        "provider": "GMAIL",
9
        "definition": {
10
          "name": "gmail_fetch_mails",
11
          "description": "Fetch emails from a connected Gmail account using search filters. Requires a valid Gmail OAuth2 connection.",
12
          "schema_version": "1",
13
          "tool_version": "1",
14
          "input_schema": {
15
            "type": "object",
16
            "properties": {
17
              "query": {
18
                "type": [
19
                  "string",
20
                  "null"
21
                ],
22
                "description": "Search query string using Gmail's search syntax (e.g., 'is:unread from:user@example.com')"
23
              },
24
              "max_results": {
25
                "type": [
26
                  "integer",
27
                  "null"
28
                ],
29
                "description": "Maximum number of emails to fetch"
30
              }
31
            }
32
          }
33
        },
34
        "is_default": true,
35
        "metadata": {},
36
        "tags": []
37
      }
38
    },
39
    {
40
      "connected_account_id": "ca_24834495392086178",
41
      "identifier": "user_123",
42
      "tool": {
43
        "id": "tol_86147403291583327",
44
        "provider": "GMAIL",
45
        "definition": {
46
          "name": "gmail_send_message",
47
          "description": "Send an email message immediately from the authenticated Gmail account. Constructs a MIME message and sends it via the Gmail API.",
48
          "schema_version": "1",
49
          "tool_version": "1",
50
          "input_schema": {
51
            "type": "object",
52
            "properties": {
53
              "to": {
54
                "type": "string",
55
                "description": "The recipient email address(es) for the message."
56
              },
57
              "subject": {
58
                "type": "string",
59
                "description": "The subject line of the email."
60
              },
61
              "body": {
62
                "type": "string",
63
                "description": "The body content of the email."
64
              }
65
            },
66
            "required": [
67
              "to",
68
              "subject",
69
              "body"
70
            ]
71
          }
72
        },
73
        "is_default": true,
74
        "metadata": {},
75
        "tags": []
76
      }
77
    }
78
  ],
79
  "next_page_token": "eyJhZnRlciI6InRvbF84NjE0NzQwMzI5MTU4MzMyNyJ9",
80
  "prev_page_token": "",
81
  "total_size": 48
82
}