Tool calling

scalekit.tools returns raw tool schemas so you can build custom agent adapters instead of using scalekit.actions.executeTool directly.

Use this client when you need tool definitions (name, parameters, connector) for frameworks or your own executor. For connect + execute flows, prefer Connected accounts. These methods throw on 4xx/5xx. See Error handling.

Pick a discovery method:

• listTools — workspace catalog
• listScopedTools — tools already bound to one identifier (the list you pass to an LLM)
• listAvailableTools — tools you can make available for that identifier
• searchTools — catalog ranked by relevance to a natural-language query, with per-connection readiness

listTools

classToolsClienthttps://github.com/scalekit-inc/scalekit-sdk-node/blob/main/src/tools.ts

#asynclistTools

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

paramoptionsobject

Optional fields: filter, pageSize, pageToken.

filter, pageSize, pageToken

returnsListToolsResponse

Paginated tools.

const res = await scalekit.tools.listTools({
  pageSize: 50,
  filter: { query: 'send message' },
});

listScopedTools

classToolsClienthttps://github.com/scalekit-inc/scalekit-sdk-node/blob/main/src/tools.ts

#asynclistScopedTools

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

paramidentifierstring

Connected account identifier to scope the tools list.

paramoptionsobject

Required: filter. Optional: pageSize, pageToken. connectionNames is the Connection name from the dashboard, not a provider slug.

filter, pageSize, pageToken

returnsListScopedToolsResponse

Paginated results.

const res = await scalekit.tools.listScopedTools('user@example.com', {
  filter: {
    connectionNames: ['github-connect'],
  },
  pageSize: 50,
});

listAvailableTools

classToolsClienthttps://github.com/scalekit-inc/scalekit-sdk-node/blob/main/src/tools.ts

#asynclistAvailableTools

Lists tools that can be made available for one identifier. Use this instead of listScopedTools when you need the candidate set, not the tools already bound.

paramidentifierstring

Connected account identifier to list available tools for.

paramoptionsobject

Optional fields: pageSize, pageToken.

pageSize, pageToken

returnsListAvailableToolsResponse

Paginated results.

const res = await scalekit.tools.listAvailableTools('user@example.com', {
  pageSize: 50,
});

searchTools

classToolsClienthttps://github.com/scalekit-inc/scalekit-sdk-node/blob/main/src/tools.ts

#asyncsearchTools

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

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

stateREADY

Usable now. Pass this connection’s connectedAccountId to executeTool.

stateNEEDS_CONNECTION

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

stateNEEDS_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 array means the identifier has no connected account for that tool’s provider. This is not an error, and it is different from NEEDS_CONNECTION.
• Several entries mean the identifier holds accounts on more than one connection for the same provider, such as two Slack workspaces.

paramquerystring

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

paramoptionsobject

Optional fields: identifier (annotates each result with readiness for that identifier’s connections), topK (defaults to 10, capped at 50).

identifier, topK

returnsSearchToolsResponse

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

import { ToolReadinessState } from '@scalekit-sdk/node';

const res = await scalekit.tools.searchTools('send a message to a slack channel', {
  identifier: 'user@example.com',
  topK: 10,
});

for (const tool of res.tools) {
  console.log(tool.name, tool.score);
  for (const connection of tool.connections) {
    // readinessState is a number at runtime — always compare against the
    // named enum constant, never a raw number or a string.
    const isReady = connection.readinessState === ToolReadinessState.READY;
    console.log(' ', connection.connectionName, isReady, connection.connectedAccountId);
  }
}

Only pass a result’s connectedAccountId to executeTool when its readinessState is ToolReadinessState.READY.

executeTool

classToolsClienthttps://github.com/scalekit-inc/scalekit-sdk-node/blob/main/src/tools.ts

#asyncexecuteTool

Executes a tool using credentials from a connected account.

paramparamsobject

Tool execution options.

toolName, identifier, params, connectedAccountId, connector, organizationId, userId

returnsExecuteToolResponse

Tool result and execution ID.

// Low-level tools client (params, not toolInput)
await scalekit.tools.executeTool({
  toolName: '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.