> **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
`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](/agentkit/sdks/python/actions/). These methods raise on 4xx/5xx. See [Error handling](/agentkit/sdks/python/errors/). 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
Lists the workspace catalog. Use this when you need every tool in the environment, not tools bound to one user. Filter by provider, identifier, or tool name Maximum tools per page. Opaque cursor from a previous list response List tools. ```python wrap showLineNumbers=false 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
Lists tools already bound to one identifier. Use this when you need the list a user is authorized to call. User connected account identifier **Required.** Optional. Filter by providers, tool names, or connection names. `connection_names` is the Connection name from the dashboard, not a provider slug. Maximum tools per page. Opaque cursor from a previous list response List scoped tools. ```python wrap showLineNumbers=false 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
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`: Usable now. Pass this connection's `connected_account_id` to `execute_tool`. 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 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. Natural-language query or keywords describing the job to be done. 1–256 characters. **Required.** Optional. Annotates each result with readiness for this identifier's connections. Optional. Maximum ranked results to return. 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. ```python wrap showLineNumbers=false 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
Low-level tool execution. Registered tool name to execute **Required.** End-user identifier. Tool arguments matching the tool input schema Connected account ID (ca_...) when you already know it ExecuteToolResponse. ```python wrap showLineNumbers=false # 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](/agentkit/tools/custom-tools/) to proxy any provider API through a connected account.
--- ## 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 |