Tool calling

List raw tool schemas for custom adapters

scalekit.tools returns raw tool schemas for custom agent adapters.

Use this when you need tool definitions for frameworks or your own executor. For connect + execute, use Connected accounts. These methods raise on 4xx/5xx. See Error handling.

Pick a discovery method:

list_tools — workspace catalog
list_scoped_tools — tools already bound to one identifier (the list you pass to an LLM)
search_tools — catalog ranked by relevance to a natural-language query, with per-connection readiness

list_available_tools is not in the Python SDK. Use GET /api/v1/tools/available or the Node listAvailableTools method.

tools.list_tools

classToolsClient

#asynctools.list_tools

Lists the workspace catalog. Use this when you need every tool in the environment, not tools bound to one user.

paramfilterFilter

Filter by provider, identifier, or tool name

parampage_sizeint

Maximum tools per page.

parampage_tokenstr

Opaque cursor from a previous list response

returnsListToolsResponse

List tools.

from scalekit.v1.tools.tools_pb2 import Filter

response = scalekit_client.tools.list_tools(
    filter=Filter(query="send message"),
    page_size=50,
)

tools.list_scoped_tools

classToolsClient

#asynctools.list_scoped_tools

Lists tools already bound to one identifier. Use this when you need the list a user is authorized to call.

paramidentifierstr

User connected account identifier Required.

paramfilterScopedToolFilter

Optional. Filter by providers, tool names, or connection names. connection_names is the Connection name from the dashboard, not a provider slug.

parampage_sizeint

Maximum tools per page.

parampage_tokenstr

Opaque cursor from a previous list response

returnsListScopedToolsResponse

List scoped tools.

from scalekit.v1.tools.tools_pb2 import ScopedToolFilter

response = scalekit_client.tools.list_scoped_tools(
    "user@example.com",
    filter=ScopedToolFilter(
        connection_names=["github-connect"],
    ),
    page_size=50,
)

tools.search_tools

classToolsClient

#asynctools.search_tools

Searches tools ranked by relevance to a natural-language query—the job to be done, not an exact tool name. Use this instead of the list methods when the catalog is large and you want the few tools that fit the task at hand.

Pass identifier to also get per-connection readiness on each result, so you can send the user through the right auth step before calling execute_tool.

Readiness is per connection, not per tool. Each entry in a result’s connections carries its own readiness_state:

stateTOOL_READINESS_STATE_READY

Usable now. Pass this connection’s connected_account_id to execute_tool.

stateTOOL_READINESS_STATE_NEEDS_CONNECTION

A connected account exists for the provider but is inactive. Send the user through the connect flow again.

stateTOOL_READINESS_STATE_NEEDS_REAUTH

The connected account needs the user to re-authorize before it can be used.

connections is populated only when you pass identifier. Two cases are easy to misread:

An empty list means the identifier has no connected account for that tool’s provider. This is not an error, and it is different from TOOL_READINESS_STATE_NEEDS_CONNECTION.
Several entries mean the identifier holds accounts on more than one connection for the same provider, such as two Slack workspaces.

paramquerystr

Natural-language query or keywords describing the job to be done. 1–256 characters. Required.

paramidentifierstr

Optional. Annotates each result with readiness for this identifier’s connections.

paramtop_kint

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

returnsSearchToolsResponse

Ranked tools, each with name, provider, description, score, and connections. score is comparable only within one response, not across calls.

from scalekit.v1.tools.tools_pb2 import TOOL_READINESS_STATE_READY

response = scalekit_client.tools.search_tools(
    query="send a message to a slack channel",
    identifier="user@example.com",
    top_k=10,
)

for tool in response[0].tools:
    print(tool.name, tool.score)
    for connection in tool.connections:
        # readiness_state is an int at runtime — always compare against the
        # named enum constant, never a raw int or a string.
        is_ready = connection.readiness_state == TOOL_READINESS_STATE_READY
        print(" ", connection.connection_name, is_ready, connection.connected_account_id)

Only pass a result’s connected_account_id to execute_tool when its readiness_state is TOOL_READINESS_STATE_READY.

tools.execute_tool

classToolsClient

#asynctools.execute_tool

Low-level tool execution.

paramtool_namestr

Registered tool name to execute Required.

paramidentifierstr

End-user identifier.

paramparamsdict

Tool arguments matching the tool input schema

paramconnected_account_idstr

Connected account ID (ca_…) when you already know it

returnsExecuteToolResponse

ExecuteToolResponse.

# Low-level ToolsClient (tool_name, identifier, params)
response = scalekit_client.tools.execute_tool(
    tool_name="gmail_fetch_mails",
    identifier="user@example.com",
    params={"query": "is:unread", "max_results": 5},
)

Note: Need a tool Scalekit doesn’t provide? See Build custom tools to proxy any provider API through a connected account.