> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Tool calling

List raw tool schemas for custom adapters
{/* The `sdk-client-page` and `sdk-method-section` wrappers are required raw
    elements, not layout decoration: `@/styles/sdk-reference.css` scopes every
    ClassBrowser override under `.sdk-client-page` so the styles survive
    ClientRouter navigation, and `.sdk-method-section` frames each method block.
    No Starlight component emits these hooks. */}

<div class="sdk-client-page">

`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](/agentkit/sdks/node/actions/). These methods throw on 4xx/5xx. See [Error handling](/agentkit/sdks/node/errors/).

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
<div class="sdk-method-section">
  
    
      

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

      
        Optional fields: `filter`, `pageSize`, `pageToken`.
      
      
        Paginated tools.
      

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

    
  
</div>

### listScopedTools
<div class="sdk-method-section">
  
    
      

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

      
        Connected account identifier to scope the tools list.
      
      
        Required: `filter`. Optional: `pageSize`, `pageToken`. `connectionNames` is the Connection name from the dashboard, not a provider slug.
      
      
        Paginated results.
      

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

    
  
</div>

### listAvailableTools
<div class="sdk-method-section">
  
    
      

      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.

      
        Connected account identifier to list available tools for.
      
      
        Optional fields: `pageSize`, `pageToken`.
      
      
        Paginated results.
      

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

    
  
</div>

### searchTools
<div class="sdk-method-section">
  
    
      

      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`:

      
        Usable now. Pass this connection's `connectedAccountId` to `executeTool`.
      
      
        A connected account exists for the provider but is inactive. Send the user through the connect flow again.
      
      
        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.

      
        Natural-language query or keywords describing the job to be done. 1–256 characters.
      
      
        Optional fields: `identifier` (annotates each result with readiness for that identifier's connections), `topK` (defaults to 10, capped at 50).
      
      
        Ranked `tools`, each with `name`, `provider`, `description`, `score`, and `connections`. `score` is comparable only within one response, not across calls.
      

```typescript wrap showLineNumbers=false

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

    
  
</div>

### executeTool
<div class="sdk-method-section">
  
    
      

      Executes a tool using credentials from a connected account.

      
        Tool execution options.
      
      
        Tool result and execution ID.
      

```typescript wrap showLineNumbers=false
// 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 },
});
```

    
  
</div>

Note: Need a tool Scalekit doesn't provide? See [Build custom tools](/agentkit/tools/custom-tools/) to proxy any provider API through a connected account.

</div>


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |