scalekit-inc · saif-at-scalekit · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026
@@ -852,6 +852,14 @@ function generateAuthSection(authPattern, providerName) {
   return `This connector uses **${authPattern.display_name || type}** authentication.`
 }
 
+function generateConnectionSetupGuidance(providerName) {
+  return `Before calling this connector from your code, create the ${providerName} connection in **AgentKit** > **Connections** and copy the exact **Connection name** from that connection into your code. The value in code must match the dashboard exactly.`
+}
+
+function generateToolListGuidance() {
+  return `Use the exact tool names from the **Tool list** below when you call \`execute_tool\`. If you're not sure which name to use, list the tools available for the current user first.`
+}
+
 // ---------------------------------------------------------------------------
 // MDX generation
 // ---------------------------------------------------------------------------
@@ -938,6 +946,8 @@ function generateMdxContent(provider, tools) {
     lines.push('')
     lines.push(generateAuthSection(primaryAuth, providerName))
     lines.push('')
+    lines.push(generateConnectionSetupGuidance(providerName))
+    lines.push('')
   }
   appendSectionComponents(lines, SECTION_ENTRIES, providerSlug, 'after-authentication')
 
@@ -970,6 +980,8 @@ function generateMdxContent(provider, tools) {
   if (tools.length > 0) {
     lines.push('## Tool list')
     lines.push('')
+    lines.push(generateToolListGuidance())
+    lines.push('')
     lines.push('<ToolList tools={tools} />')
     lines.push('')
   }

@@ -32,6 +32,7 @@ Register your Scalekit environment with the Google Calendar connector so Scaleki
 4. ### Add credentials in Scalekit
 
     - In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** and open the connection you created.
+    - Copy the **Connection name** shown on that connection and use that exact value in your code as `connection_name` or `connectionName`. It may be something like `meeting-prep-agent-googlecalendar`, not `googlecalendar`.
     - Enter your credentials:
       - Client ID (from above)
       - Client Secret (from above)

@@ -1,4 +1,4 @@
-import { Steps, Aside } from '@astrojs/starlight/components'
+import { Steps } from '@astrojs/starlight/components'
 
 Register your Scalekit environment with the HubSpot connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:
 
@@ -9,13 +9,19 @@ Register your Scalekit environment with the HubSpot connector so Scalekit handle
 
       ![Copy redirect URI from Scalekit dashboard](@/assets/docs/agent-connectors/hubspot/use-own-credentials-redirect-uri.png)
 
-    - Log in to your [HubSpot developer dashboard](https://developers.hubspot.com/), click **Manage apps**, and open your app (or create one if you have not already).
+    - Log in to your [HubSpot developer dashboard](https://developers.hubspot.com/), click **Manage apps**, click **Create app**, and select **Public app**. Do not select **Private app**; Private Apps use static API tokens and do not support OAuth redirect flows, so they do not show the Redirect URL field Scalekit needs. If you already have a HubSpot Public App, open that app instead.
 
     - Go to **Auth** > **Auth settings** > **Redirect URL**, paste the redirect URI from Scalekit, and click **Save**.
 
       ![Adding redirect URL to HubSpot](@/assets/docs/agent-connectors/hubspot/add-redirect-url.png)
 
-    - Under **Auth** > **Auth settings** > **Scopes**, select the required scopes for your application. The scopes you select here must match exactly what you configure in Scalekit.
+    - Under **Auth** > **Auth settings** > **Scopes**, select the required scopes for your application. The scopes you select here must match exactly what you configure in Scalekit. For a read-only CRM enrichment flow that looks up contacts, companies, and deals, use:
+
+      ```text
+      crm.objects.contacts.read
+      crm.objects.companies.read
+      crm.objects.deals.read
+      ```
 
 2. ### Get client credentials
 
@@ -30,11 +36,7 @@ Register your Scalekit environment with the HubSpot connector so Scalekit handle
     - Enter your credentials:
       - **Client ID** (from your HubSpot app)
       - **Client Secret** (from your HubSpot app)
-      - **Permissions** (OAuth scopes — see [HubSpot scopes reference](https://developers.hubspot.com/docs/api/overview))
-
-      <Aside type="caution" title="Scopes must match exactly">
-        The scopes selected in your HubSpot app must exactly match the scopes you enter in Scalekit. A mismatch breaks the OAuth flow.
-      </Aside>
+      - **Permissions** (OAuth scope strings such as `crm.objects.contacts.read`, entered exactly as configured in the HubSpot app)
 
       ![Add credentials in Scalekit dashboard](@/assets/docs/agent-connectors/hubspot/add-credentials.png)
 

@@ -1,4 +1,4 @@
-import { Steps, Aside } from '@astrojs/starlight/components'
+import { Steps } from '@astrojs/starlight/components'
 
 Register your Scalekit environment with the Slack connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:
 
@@ -21,7 +21,13 @@ Register your Scalekit environment with the Slack connector so Scalekit handles
 
 2. ### Enable distribution
 
-    - In your Slack app settings, go to **Manage Distribution** and enable it.
+    - In your Slack app settings, go to **Manage Distribution**.
+
+    - Under **Share Your App with Other Workspaces**, complete the checklist Slack shows for your app. This can include accepting Slack's distribution agreement, adding support and privacy URLs, and confirming that the redirect URL you added above is valid.
+
+    - Click **Activate Public Distribution**.
+
+      Slack app distribution must be active before users can authorize the app from external workspaces. If distribution is not active, OAuth can succeed in your development workspace but fail when a user tries to connect a second workspace.
 
       ![Enable Slack app distribution](@/assets/docs/agent-connectors/slack/enable-distribution.png)
 
@@ -31,6 +37,8 @@ Register your Scalekit environment with the Slack connector so Scalekit handles
 
     - In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** and open the connection you created.
 
+    Choose **Bot scope** for most agents, including agents that read channel history or send messages as your Slack app. Bot scope makes the agent act as the Slack app or bot; use **User scope** only when the agent must act as the authorizing Slack user.
+
     - Enter your credentials:
       - Client ID
       - Client Secret

@@ -268,6 +268,7 @@ scalekit_client = ScalekitClient(
 tools = scalekit_client.actions.langchain.get_tools(
     providers=["BRAVE_SEARCH"],
     identifier="user_123",
+    page_size=100,  # avoid missing tools when a connector has more than the default page
 )
 
 llm = ChatAnthropic(

@@ -311,7 +311,7 @@ actions.get_or_create_connected_account(
     identifier=identifier
 )
 
-# Load all Exa tools in LangChain format
+# Load all Exa tools in LangChain format. Use page_size=100 so connector tool lists are not truncated.
 tools = actions.langchain.get_tools(
     identifier=identifier,
     providers=["EXA"],

@@ -2,6 +2,128 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'
 
 Connect a user's Gmail account and make API calls on their behalf — Scalekit handles OAuth and token management automatically.
 
+## Discover tool names
+
+Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for this Gmail connection first.
+
+<Tabs syncKey="tech-stack">
+  <TabItem label="Node.js">
+    ```typescript
+    import { ScalekitClient } from '@scalekit-sdk/node';
+    import 'dotenv/config';
+
+    const connectionName = 'your-gmail-connection'; // copy the exact Connection name from AgentKit > Connections
+    const identifier = 'user_123'; // your unique user identifier
+
+    const scalekit = new ScalekitClient(
+      process.env.SCALEKIT_ENV_URL,
+      process.env.SCALEKIT_CLIENT_ID,
+      process.env.SCALEKIT_CLIENT_SECRET
+    );
+
+    const { tools } = await scalekit.tools.listScopedTools(identifier, {
+      filter: { connectionNames: [connectionName] },
+      pageSize: 100,
+    });
+
+    for (const scopedTool of tools) {
+      console.log('Available tool:', scopedTool.tool?.definition?.name);
+    }
+    ```
+  </TabItem>
+  <TabItem label="Python">
+    ```python
+    import os
+    import scalekit.client
+    from dotenv import load_dotenv
+    from google.protobuf.json_format import MessageToDict
+    from scalekit.v1.tools.tools_pb2 import ScopedToolFilter
+
+    load_dotenv()
+
+    connection_name = "your-gmail-connection"  # copy the exact Connection name from AgentKit > Connections
+    identifier = "user_123"  # your unique user identifier
+
+    scalekit_client = scalekit.client.ScalekitClient(
+        client_id=os.getenv("SCALEKIT_CLIENT_ID"),
+        client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
+        env_url=os.getenv("SCALEKIT_ENV_URL"),
+    )
+    actions = scalekit_client.actions
+
+    scoped_response, _ = actions.tools.list_scoped_tools(
+        identifier=identifier,
+        filter=ScopedToolFilter(connection_names=[connection_name]),
+        page_size=100,
+    )
+
+    for scoped_tool in scoped_response.tools:
+        definition = MessageToDict(scoped_tool.tool).get("definition", {})
+        print("Available tool:", definition.get("name"))
+    ```
+  </TabItem>
+</Tabs>
+
+## Use Gmail response fields as returned
+
+Response fields from Gmail tools use camelCase, such as `threadId`, `messageId`, and `internalDate`. Tool input parameters use the snake_case names shown in the Tool list, such as `thread_id` and `message_id`. Extract values with camelCase, then pass them with snake_case. The snippets below assume you already have an active connected account ID for the user.
+
+<Tabs syncKey="tech-stack">
+  <TabItem label="Node.js">
+    ```typescript
+    const fetchResponse = await actions.executeTool({
+      toolName: 'gmail_fetch_mails',
+      connectedAccountId,
+      toolInput: {
+        query: 'is:unread',
+        max_results: 5,
+      },
+    });
+
+    const messages = Array.isArray(fetchResponse.data?.messages)
+      ? fetchResponse.data.messages
+      : [];
+    const threadId = typeof messages[0]?.threadId === 'string' ? messages[0].threadId : '';
+
+    const threadResponse = await actions.executeTool({
+      toolName: 'gmail_get_thread_by_id',
+      connectedAccountId,
+      toolInput: {
+        thread_id: threadId,
+      },
+    });
+
+    console.log(threadResponse.data);
+    ```
+  </TabItem>
+  <TabItem label="Python">
+    ```python
+    fetch_response = actions.execute_tool(
+        tool_name="gmail_fetch_mails",
+        connected_account_id=connected_account.id,
+        tool_input={
+            "query": "is:unread",
+            "max_results": 5,
+        },
+    )
+
+    data = fetch_response.data or {}
+    messages = data.get("messages", [])
+    thread_id = messages[0].get("threadId", "") if messages else ""
+
+    thread_response = actions.execute_tool(
+        tool_name="gmail_get_thread_by_id",
+        connected_account_id=connected_account.id,
+        tool_input={
+            "thread_id": thread_id,
+        },
+    )
+
+    print(thread_response.data)
+    ```
+  </TabItem>
+</Tabs>
+
 ## Proxy API Calls
 
 <Tabs syncKey="tech-stack">
@@ -77,4 +199,3 @@ Connect a user's Gmail account and make API calls on their behalf — Scalekit h
     ```
   </TabItem>
 </Tabs>
-