> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a toolkit

> Connect a third-party toolkit with OAuth or an API key, then monitor and repair its connection health.

export const Browser = ({url, children}) => <div className="tars-browser">
    <div className="tars-browser-bar">
      <span className="tars-browser-dots">
        <i />
        <i />
        <i />
      </span>
      {url ? <span className="tars-browser-url">{url}</span> : null}
    </div>
    <div className="tars-browser-view">{children}</div>
  </div>;

export const img = {
  activity: {
    activityTimeline: "/docs/guides/activity/images/activity-timeline.png",
    capturedVariablesPanel: "/docs/guides/activity/images/captured-variables-panel.png",
    dataViewCards: "/docs/guides/activity/images/data-view-cards.png",
    exportDataDialog: "/docs/guides/activity/images/export-data-dialog.png",
    tasksPanelExportReady: "/docs/guides/activity/images/tasks-panel-export-ready.png"
  },
  analytics: {
    analyticsOverview: "/docs/guides/analytics/images/analytics-overview.png",
    exploreGallery: "/docs/guides/analytics/images/explore-gallery.png",
    exploreTab: "/docs/guides/analytics/images/explore-tab.png",
    goalForm: "/docs/guides/analytics/images/goal-form.png",
    goalsTab: "/docs/guides/analytics/images/goals-tab.png",
    improveDiagnostics: "/docs/guides/analytics/images/improve-diagnostics.png",
    improveTab: "/docs/guides/analytics/images/improve-tab.png",
    teamTab: "/docs/guides/analytics/images/team-tab.png"
  },
  billing: {
    billingOverview: "/docs/guides/billing/images/billing-overview.png",
    buyConversationsDialog: "/docs/guides/billing/images/buy-conversations-dialog.png",
    buySeatsDialog: "/docs/guides/billing/images/buy-seats-dialog.png",
    livechatSeatsTab: "/docs/guides/billing/images/livechat-seats-tab.png",
    organizationDeletionLifecycle: "/docs/guides/billing/images/organization-deletion-lifecycle.svg",
    organizationSwitcher: "/docs/guides/billing/images/organization-switcher.png",
    rolesAndAccessMatrix: "/docs/guides/billing/images/roles-and-access-matrix.png"
  },
  building: {
    agentBehaviorGuardrails: "/docs/guides/building/images/agent-behavior-guardrails.png",
    agentCardMenu: "/docs/guides/building/images/agent-card-menu.png",
    agentConfigure: "/docs/guides/building/images/agent-configure.png",
    agentExitRoutesDialog: "/docs/guides/building/images/agent-exit-routes-dialog.png",
    agentLibrary: "/docs/guides/building/images/agent-library.png",
    agentModelParameters: "/docs/guides/building/images/agent-model-parameters.png",
    aiAgentGambitLoop: "/docs/guides/building/images/ai-agent-gambit-loop.svg",
    builderBasics: "/docs/guides/building/images/builder-basics.png",
    builderConnectHandlePanel: "/docs/guides/building/images/builder-connect-handle-panel.png",
    builtInToolsDialog: "/docs/guides/building/images/built-in-tools-dialog.png",
    configureDebugTab: "/docs/guides/building/images/configure-debug-tab.png",
    configureLanguage: "/docs/guides/building/images/configure-language.png",
    configureNotifications: "/docs/guides/building/images/configure-notifications.png",
    createAgentDialog: "/docs/guides/building/images/create-agent-dialog.png",
    draftPublishRollbackPinning: "/docs/guides/building/images/draft-publish-rollback-pinning.svg",
    draftSwitcherChip: "/docs/guides/building/images/draft-switcher-chip.png",
    duplicateAgentDialog: "/docs/guides/building/images/duplicate-agent-dialog.png",
    flowConditions: "/docs/guides/building/images/flow-conditions.png",
    gambitPalette: "/docs/guides/building/images/gambit-palette.png",
    gambits: {
      gambitAiAgent: "/docs/guides/building/gambits/images/gambit-ai-agent.png",
      gambitApiCall: "/docs/guides/building/gambits/images/gambit-api-call.png",
      gambitAutoSuggestion: "/docs/guides/building/gambits/images/gambit-auto-suggestion.png",
      gambitButton: "/docs/guides/building/gambits/images/gambit-button.png",
      gambitCard: "/docs/guides/building/gambits/images/gambit-card.png",
      gambitChannel: "/docs/guides/building/gambits/images/gambit-channel.png",
      gambitCustomCode: "/docs/guides/building/gambits/images/gambit-custom-code.png",
      gambitDateTime: "/docs/guides/building/gambits/images/gambit-date-time.png",
      gambitGeoLocation: "/docs/guides/building/gambits/images/gambit-geo-location.png",
      gambitLanguage: "/docs/guides/building/gambits/images/gambit-language.png",
      gambitLiveChat: "/docs/guides/building/gambits/images/gambit-live-chat.png",
      gambitMediaUpload: "/docs/guides/building/gambits/images/gambit-media-upload.png",
      gambitNoInput: "/docs/guides/building/gambits/images/gambit-no-input.png",
      gambitRedirect: "/docs/guides/building/gambits/images/gambit-redirect.png",
      gambitStarRating: "/docs/guides/building/gambits/images/gambit-star-rating.png",
      gambitStartAndEnd: "/docs/guides/building/gambits/images/gambit-start-and-end.png",
      gambitText: "/docs/guides/building/gambits/images/gambit-text.png",
      gambitTrigger: "/docs/guides/building/gambits/images/gambit-trigger.png"
    },
    languagesTranslateGambit: "/docs/guides/building/images/languages-translate-gambit.png",
    languageSystemMessages: "/docs/guides/building/images/language-system-messages.png",
    newDraftDialog: "/docs/guides/building/images/new-draft-dialog.png",
    outputComponentsGrid: "/docs/guides/building/images/output-components-grid.png",
    publishDialog: "/docs/guides/building/images/publish-dialog.png",
    systemPromptDialog: "/docs/guides/building/images/system-prompt-dialog.png",
    testModeEventLog: "/docs/guides/building/images/test-mode-event-log.png",
    testModePanel: "/docs/guides/building/images/test-mode-panel.png",
    validationProblemsPanel: "/docs/guides/building/images/validation-problems-panel.png",
    variablePickerPanel: "/docs/guides/building/images/variable-picker-panel.png",
    variablePillInserted: "/docs/guides/building/images/variable-pill-inserted.png",
    versionsDraftsPanel: "/docs/guides/building/images/versions-drafts-panel.png"
  },
  campaigns: {
    campaignFlavorsTriggers: "/docs/guides/campaigns/images/campaign-flavors-triggers.svg",
    campaignReplyRouting: "/docs/guides/campaigns/images/campaign-reply-routing.svg",
    campaignSendAnatomy: "/docs/guides/campaigns/images/campaign-send-anatomy.svg",
    createACampaign: "/docs/guides/campaigns/images/create-a-campaign.png",
    walletReserveSettleRefund: "/docs/guides/campaigns/images/wallet-reserve-settle-refund.svg",
    webhookCampaignContractLocking: "/docs/guides/campaigns/images/webhook-campaign-contract-locking.svg",
    webhookCampaignLifecycleStates: "/docs/guides/campaigns/images/webhook-campaign-lifecycle-states.svg",
    webhookCampaignOneCallOneDelivery: "/docs/guides/campaigns/images/webhook-campaign-one-call-one-delivery.svg"
  },
  channels: {
    distributeWhatsappConnect: "/docs/guides/channels/images/distribute-whatsapp-connect.png",
    whatsappConnectDialogWaiting: "/docs/guides/channels/images/whatsapp-connect-dialog-waiting.png",
    whatsappEmptyState: "/docs/guides/channels/images/whatsapp-empty-state.png"
  },
  deploy: {
    bridgeEventGambitSection: "/docs/guides/deploy/images/bridge-event-gambit-section.png",
    deploymentSurfacesAndChannels: "/docs/guides/deploy/images/deployment-surfaces-and-channels.svg",
    designAgentTab: "/docs/guides/deploy/images/design-agent-tab.png",
    designLauncherTab: "/docs/guides/deploy/images/design-launcher-tab.png",
    embedIframeTab: "/docs/guides/deploy/images/embed-iframe-tab.png",
    embedTheWidget: "/docs/guides/deploy/images/embed-the-widget.png",
    mobileAppIntegration: "/docs/guides/deploy/images/mobile-app-integration.png",
    onYourDomain: "/docs/guides/deploy/images/on-your-domain.png",
    shareYourAgentLink: "/docs/guides/deploy/images/share-your-agent-link.png"
  },
  developer: {
    api: {
      channelSendTemplateVsMessage: "/docs/developer/api/images/channel-send-template-vs-message.svg",
      endUsers: {
        endUsersListCursorPagination: "/docs/developer/api/end-users/images/end-users-list-cursor-pagination.svg"
      },
      triggerCallConversationLifecycle: "/docs/developer/api/images/trigger-call-conversation-lifecycle.svg"
    },
    developerSurfacesMap: "/docs/developer/images/developer-surfaces-map.svg",
    embed: {
      embedConfigToWidgetContext: "/docs/developer/embed/images/embed-config-to-widget-context.svg",
      hostPageBridgeFlow: "/docs/developer/embed/images/host-page-bridge-flow.svg",
      identitySigningFlow: "/docs/developer/embed/images/identity-signing-flow.svg",
      scriptVsIframeEmbed: "/docs/developer/embed/images/script-vs-iframe-embed.svg"
    },
    mobile: {
      bridgeMessageProtocol: "/docs/developer/mobile/images/bridge-message-protocol.svg",
      webviewBridgeArchitecture: "/docs/developer/mobile/images/webview-bridge-architecture.svg"
    }
  },
  endUsers: {
    anonymousToIdentifiedProfile: "/docs/guides/end-users/images/anonymous-to-identified-profile.svg",
    bulkActionBar: "/docs/guides/end-users/images/bulk-action-bar.png",
    campaignConsentGate: "/docs/guides/end-users/images/campaign-consent-gate.svg",
    consentPerChannelStates: "/docs/guides/end-users/images/consent-per-channel-states.svg",
    dynamicVsStaticSegments: "/docs/guides/end-users/images/dynamic-vs-static-segments.svg",
    endUserDirectory: "/docs/guides/end-users/images/end-user-directory.png",
    endUserProfileAcrossChannels: "/docs/guides/end-users/images/end-user-profile-across-channels.svg",
    endUserProfilePanes: "/docs/guides/end-users/images/end-user-profile-panes.png",
    profileMergeAndTakeoverProtection: "/docs/guides/end-users/images/profile-merge-and-takeover-protection.svg",
    segmentBuilder: "/docs/guides/end-users/images/segment-builder.png",
    segmentsPage: "/docs/guides/end-users/images/segments-page.png"
  },
  getStarted: {
    agentStates: "/docs/get-started/images/agent-states.svg",
    buildToLivePath: "/docs/get-started/images/build-to-live-path.svg",
    dashboardSidebarMap: "/docs/get-started/images/dashboard-sidebar-map.png",
    organizationOwnershipAndRoles: "/docs/get-started/images/organization-ownership-and-roles.svg",
    quickstart: {
      step1CreateYourAccount: "/docs/get-started/images/quickstart/step-1-create-your-account.png",
      step3ConnectTheAiAgent: "/docs/get-started/images/quickstart/step-3-connect-the-ai-agent.png",
      step4TestMode: "/docs/get-started/images/quickstart/step-4-test-mode.png"
    },
    quickstartCanvas: "/docs/get-started/images/quickstart-canvas.png"
  },
  knowledge: {
    addASource: "/docs/guides/knowledge/images/add-a-source.png",
    addRetrieverPicker: "/docs/guides/knowledge/images/add-retriever-picker.png",
    attachKnowledgeGambit: "/docs/guides/knowledge/images/attach-knowledge-gambit.png",
    configureARetriever: "/docs/guides/knowledge/images/configure-a-retriever.png",
    createKnowledgeBaseDialog: "/docs/guides/knowledge/images/create-knowledge-base-dialog.png",
    customRetrieverDialog: "/docs/guides/knowledge/images/custom-retriever-dialog.png",
    datasetTab: "/docs/guides/knowledge/images/dataset-tab.png",
    documentChangeReindexLifecycle: "/docs/guides/knowledge/images/document-change-reindex-lifecycle.svg",
    documentsTabPreview: "/docs/guides/knowledge/images/documents-tab-preview.png",
    importAWebsite: "/docs/guides/knowledge/images/import-a-website.png",
    kbList: "/docs/guides/knowledge/images/kb-list.png",
    retrieverIndexStates: "/docs/guides/knowledge/images/retriever-index-states.svg",
    retrieverQueryPipeline: "/docs/guides/knowledge/images/retriever-query-pipeline.svg",
    standardVsParentChildChunking: "/docs/guides/knowledge/images/standard-vs-parent-child-chunking.svg",
    syncManagement: "/docs/guides/knowledge/images/sync-management.png",
    testRetriever: "/docs/guides/knowledge/images/test-retriever.png"
  },
  liveChat: {
    agentWorkspace: "/docs/guides/live-chat/images/agent-workspace.png",
    assignedAgentPicker: "/docs/guides/live-chat/images/assigned-agent-picker.png",
    automaticAssignmentRouting: "/docs/guides/live-chat/images/automatic-assignment-routing.svg",
    availabilityDropdown: "/docs/guides/live-chat/images/availability-dropdown.png",
    cannedResponses: "/docs/guides/live-chat/images/canned-responses.png",
    composerPreferences: "/docs/guides/live-chat/images/composer-preferences.png",
    copilotPanel: "/docs/guides/live-chat/images/copilot-panel.png",
    filterConversationsDialog: "/docs/guides/live-chat/images/filter-conversations-dialog.png",
    inboxAnalyticsTab: "/docs/guides/live-chat/images/inbox-analytics-tab.png",
    inboxAvailabilityTab: "/docs/guides/live-chat/images/inbox-availability-tab.png",
    inboxesSettings: "/docs/guides/live-chat/images/inboxes-settings.png",
    inboxRoutingTab: "/docs/guides/live-chat/images/inbox-routing-tab.png",
    labelsSettings: "/docs/guides/live-chat/images/labels-settings.png",
    newAttributeDialog: "/docs/guides/live-chat/images/new-attribute-dialog.png",
    newCannedResponseDialog: "/docs/guides/live-chat/images/new-canned-response-dialog.png",
    notificationPreferences: "/docs/guides/live-chat/images/notification-preferences.png",
    notificationsPage: "/docs/guides/live-chat/images/notifications-page.png",
    pickupTargetCard: "/docs/guides/live-chat/images/pickup-target-card.png",
    resolveMenu: "/docs/guides/live-chat/images/resolve-menu.png",
    searchDialog: "/docs/guides/live-chat/images/search-dialog.png",
    seatGateConversation: "/docs/guides/live-chat/images/seat-gate-conversation.png",
    seatsSettings: "/docs/guides/live-chat/images/seats-settings.png",
    workTheInbox: "/docs/guides/live-chat/images/work-the-inbox.png"
  },
  security: {
    addOpenRouterKeyDialog: "/docs/guides/security/images/add-open-router-key-dialog.png",
    auditChainVerified: "/docs/guides/security/images/audit-chain-verified.png",
    auditEventDrawer: "/docs/guides/security/images/audit-event-drawer.png",
    auditExportDialog: "/docs/guides/security/images/audit-export-dialog.png",
    auditLogViewer: "/docs/guides/security/images/audit-log-viewer.png",
    auditRecordLifecycle: "/docs/guides/security/images/audit-record-lifecycle.svg",
    logPrivacyRedactionEnabled: "/docs/guides/security/images/log-privacy-redaction-enabled.png",
    modelProviderEmptyState: "/docs/guides/security/images/model-provider-empty-state.png",
    privacySettings: "/docs/guides/security/images/privacy-settings.png",
    siemConnectWizard: "/docs/guides/security/images/siem-connect-wizard.png",
    supportActorMasking: "/docs/guides/security/images/support-actor-masking.svg"
  },
  tools: {
    addToolModal: "/docs/guides/tools/images/add-tool-modal.png",
    addToolsPanel: "/docs/guides/tools/images/add-tools-panel.png",
    codekitActionEditor: "/docs/guides/tools/images/codekit-action-editor.png",
    codekitConnectToolkitsDialog: "/docs/guides/tools/images/codekit-connect-toolkits-dialog.png",
    codekitSchemaDialog: "/docs/guides/tools/images/codekit-schema-dialog.png",
    codekitToolkit: "/docs/guides/tools/images/codekit-toolkit.png",
    codekitToolkitAnatomy: "/docs/guides/tools/images/codekit-toolkit-anatomy.svg",
    createActionDialog: "/docs/guides/tools/images/create-action-dialog.png",
    createCodekitDialog: "/docs/guides/tools/images/create-codekit-dialog.png",
    responseFilteringDialog: "/docs/guides/tools/images/response-filtering-dialog.png",
    toolGambitEditorAgentMode: "/docs/guides/tools/images/tool-gambit-editor-agent-mode.png",
    toolGambitEditorWorkflowMode: "/docs/guides/tools/images/tool-gambit-editor-workflow-mode.png",
    toolkitDetail: "/docs/guides/tools/images/toolkit-detail.png",
    toolsConnected: "/docs/guides/tools/images/tools-connected.png",
    toolsDirectory: "/docs/guides/tools/images/tools-directory.png",
    viewActionsModal: "/docs/guides/tools/images/view-actions-modal.png",
    workflowModeResponse: "/docs/guides/tools/images/workflow-mode-response.png"
  }
};

export const urls = {
  app: "https://dashboard.hellotars.com",
  site: "https://hellotars.com",
  support: "mailto:support@hellotars.com",
  status: "https://status.hellotars.com"
};

At the end of this page, you have a connected toolkit whose actions your agents can call.

## Before you start

Before you start, sign in to <a href={urls.app}>the dashboard</a> and select the organization you want to work in.

* You need a role that can manage resources. See [Roles and permissions](/docs/guides/billing/roles-and-permissions).
* For an API-key connection, have the provider credentials ready.
* Allow pop-up windows for the dashboard. OAuth authorization opens in a new browser tab.

## Connect from the Directory

<Browser url={urls.app}>
  <img src={img.tools.toolsDirectory} alt="The Tools page on the Directory tab, with category pills for All, Connected, and Featured, and toolkit cards offering View actions and Add Tool buttons" />
</Browser>

<Steps>
  <Step title="Open Tools in the sidebar and select the Directory tab">
    Use the category pills, or search for the provider name.
  </Step>

  <Step title="Select Add Tool on the toolkit card">
    Or open **View {"{n}"} actions** first, then select **Add Tool** in the footer.
  </Step>

  <Step title="Enter a Connection Name">
    The name is optional for OAuth toolkits.
  </Step>

  <Step title="Pick a Toolkit version">
    Keep the default latest version unless you need an older action set.
  </Step>

  <Step title="Fill the required fields and select Connect">
    For OAuth, the provider page opens in a new tab. Sign in and approve access there.
    For an API key, a toast confirms the connection or asks you to fill all required fields.
  </Step>
</Steps>

The modal closes and the toolkit detail page opens. Enable the actions your agents can use there. See [Enable and use actions](/docs/guides/tools/enable-and-use-actions).

### The Add Tool modal

The modal opens with the toolkit logo, name, description, and a **Featured** badge when it applies. Its fields, top to bottom:

<Frame>
  <img src={img.tools.addToolModal} alt="The Add Tool modal for Gmail with the Connection Name field, the Toolkit version selector, the View actions link, and the Connect button" />
</Frame>

| Field               | What it does                                                                                                                                                                             |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection Name** | A label that tells multiple connections apart, for example "Sales Gmail". The label reads **Connection Name (optional)** when the toolkit supports OAuth.                                |
| **Toolkit version** | Appears only when the toolkit has versions, with the latest selected by default. The version determines the set of actions available. Newer versions may add, remove, or change actions. |
| **Actions**         | **View {"{n}"} actions** for the selected version opens the actions modal.                                                                                                               |
| Credential fields   | For OAuth, any provider fields the authorization needs. For an API key, one masked field per credential. Required fields carry a red asterisk.                                           |
| **Connect**         | Starts the connection.                                                                                                                                                                   |

Some credential fields link to a provider help page, labeled **How to find this?** or **How to get this?**.

The modal picks the authentication path for you. Toolkits that support OAuth connect with OAuth. Toolkits that only support an API key show the credential fields. To connect a toolkit that supports both with an API key, use the **OAuth** and **API Key** switch in the [Add another account dialog](#add-another-account).

## The authorization tab

An OAuth connection opens a new tab with the provider sign-in page. Some paths first show "Redirecting to authorization…". After you approve access, the tab returns to Tars and reports the outcome:

| Heading                                         | Meaning                                                                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Syncing your connection...**                  | Tars is completing the setup. Wait.                                                                      |
| **Your tool has been authorized successfully!** | The connection is active. The tab closes itself.                                                         |
| **Authorization failed**                        | The connection was not activated. The reason appears under the heading, and the tab closes itself.       |
| **Oops! Authorization failed**                  | The provider rejected the authorization. Try again later, or follow the link back to the **Tools** page. |

If the tab does not close, a link offers to head back to the **Tools** page. The dashboard tab that started the connection updates on its own.

## Finish a pending authorization

Until you approve access, the **Authorization** card on the toolkit detail page reads **Waiting for authentication** with an **Initiated** badge. It shows a countdown and a **Complete authentication** button that reopens the provider page.

When the countdown ends, the card reads **Authentication expired** with an **Expired** badge.

## Add another account

The toolkit detail page connects more accounts of the same toolkit. Select **Add {"{toolkit name}"}** in the header. The **Add {"{toolkit name}"}** dialog opens with the subtitle "Connect another {"{toolkit name}"} account."

When the toolkit supports both methods, **OAuth** and **API Key** buttons switch between the two forms. Each form has the same fields as the **Add Tool** modal and ends with **Connect**. The new connection appears in the account picker of the detail page.

## Rotate API-key credentials

An API-key connection carries a **Credentials** card on the toolkit detail page. It lists every credential field with its value masked, and each field has an eye button that shows or hides the value. A **Last updated** date sits under the fields.

<Steps>
  <Step title="Open Tools and select Configure on the connection">
    Pick the right account in the account picker first.
  </Step>

  <Step title="Select Edit on the Credentials card">
    The fields become editable. **Edit** is shown only to members who can manage resources.
  </Step>

  <Step title="Enter the new values and select Update">
    Tars reconnects with the new credentials.

    <Check>
      A **Credentials updated** message confirms, and the card leaves edit mode.
    </Check>
  </Step>
</Steps>

Rotating this way keeps the connection, so enabled actions and the agents that use them are untouched.

## Change the connected account

An active connection has a **Change account** button on its **Authorization** card. The button is shown only to members who can manage resources.

<Steps>
  <Step title="Open Tools and select Configure on the connection">
    Pick the right account in the account picker first.
  </Step>

  <Step title="Select Change account on the Authorization card">
    The dialog states how many gambits and agents use the connection. The change applies to all of them.
  </Step>

  <Step title="For an API key, enter a new value for each credential field">
    Skip this step for an OAuth connection.
  </Step>

  <Step title="Select Change account in the dialog">
    An API-key connection confirms with **Account changed**. An OAuth connection first refreshes the existing authorization.

    <Check>
      A **Connection refreshed** message confirms. If the provider needs a new approval, a new tab opens instead.
    </Check>
  </Step>
</Steps>

## Connection health

The badge on the **Connected** tab card tells you whether agents can call the toolkit. Only a **Connected** connection runs actions, and the action toggles on the toolkit detail page are disabled in every other state.

| Badge             | Meaning                                                                                           | What to do                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Connected**     | The connection is active.                                                                         | Nothing.                                                   |
| **Initiated**     | Authorization is pending.                                                                         | Open **Configure** and select **Complete authentication**. |
| **Expired**       | The provider credentials expired.                                                                 | Open **Configure** and select **Reconnect**.               |
| **Error**         | The connection failed.                                                                            | Open **Configure** and select **Reconnect**.               |
| **Revoked**       | Access was revoked in Tars or by the provider.                                                    | Open **Configure** and select **Restore access**.          |
| **Not Connected** | The connection was disconnected.                                                                  | Open **Configure** and select **Add new connection**.      |
| **Not found**     | Shown on the **Authorization** card when the provider no longer recognizes the connected account. | Select the refresh control on the card.                    |

The **Authorization** card on the toolkit detail page shows the same state with its repair button.

<Warning>
  Revoking access disconnects the tool and may break any agents currently using it. The **Revoke access** dialog confirms this, and you can restore access at any time.
</Warning>

## When a provider revokes access

Providers can remove access outside Tars, for example after a password change or a provider-side policy change. When you open the toolkit detail page, Tars checks the provider and updates the badge to **Revoked** or **Expired**. Agents cannot call the toolkit's actions until you reconnect.

<Steps>
  <Step title="Open Tools and select Configure on the affected connection">
    The **Authorization** card states the connection state.
  </Step>

  <Step title="Select Reconnect or Restore access">
    **Reconnect** first refreshes the existing authorization. If the provider rejects the refresh, a new authorization tab opens.
  </Step>
</Steps>

Enabled actions and settings are kept, because reconnection replaces only the credentials. If the authorization cannot start, an error message asks you to try again. **Reconnect** is shown only to members who can manage resources.

## Verify

Open the **Connected** tab. The toolkit card shows a **Connected** badge and its enabled action count. Its detail page says **Connection active** and **Ready for real execution**.

## The Tools page

**Tools** in the sidebar opens the page, titled **Tools** with the subtitle "Connect integrations and build custom tools for your agents".

| Control             | What it does                                                                                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search tools...** | Filters the current tab by toolkit name and description as you type.                                                                                                             |
| **Create Tool**     | Opens the **Create Custom Tool** dialog for a CodeKit toolkit. Shown only to members who can manage resources. See [Write a custom action](/docs/guides/tools/write-a-custom-action). |
| Filter button       | Opens the **Filter tools** popover. Shown only on the **Connected** tab.                                                                                                         |
| **Connected (n)**   | The default tab. Lists your connections and CodeKit toolkits. The count follows your search and filters.                                                                         |
| **Directory (n)**   | Lists every toolkit you can connect.                                                                                                                                             |

### The Directory tab

The **All**, **Connected**, and **Featured** category pills sit above the grid and hide while you search. **Connected** appears once a toolkit is connected. Featured toolkits sort first, then the rest sort by name.

Each card shows the toolkit logo, name, and description. A **Connected** badge marks toolkits you already connected, and a **Featured** badge marks highlighted ones. Two buttons sit on each card:

| Button                   | What it does                             |
| ------------------------ | ---------------------------------------- |
| **View {"{n}"} actions** | Opens the actions modal for the toolkit. |
| **Add Tool**             | Opens the **Add Tool** modal.            |

### The Connected tab

<Browser url={urls.app}>
  <img src={img.tools.toolsConnected} alt="The Tools page on the Connected tab, with CodeKit toolkit cards that each carry Configure, Duplicate toolkit, and delete buttons, and Google Sheets and Gmail cards showing a Connected badge and their enabled action counts" />
</Browser>

When nothing is connected yet, the tab shows "No tools connected yet" and points you to the **Directory** tab. Each connection card shows:

| Element                                         | Meaning                                                                                                                                                                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Logo, name, description                         | The connection name, with the toolkit name under it. "No description available" is the fallback.                                                                                                         |
| Status badge                                    | The connection state: **Connected**, **Initiated**, **Expired**, **Error**, **Revoked**, or **Not Connected**. CodeKit toolkits show no connection badge.                                                |
| Time stamp                                      | How long ago the connection was created.                                                                                                                                                                 |
| **{"{enabled}"} / {"{total}"} actions enabled** | How many of the toolkit's actions your agents can call.                                                                                                                                                  |
| **Configure**                                   | Opens the toolkit detail page. See [Enable and use actions](/docs/guides/tools/enable-and-use-actions).                                                                                                       |
| Copy icon                                       | **Duplicate toolkit**. Shown on CodeKit toolkit cards to members who can manage resources. See [Duplicate an action or a toolkit](/docs/guides/tools/write-a-custom-action#duplicate-an-action-or-a-toolkit). |
| Trash icon                                      | **Delete connection**. Shown only to organization admins.                                                                                                                                                |

The filter button opens the **Filter tools** popover. It has a **Reset all** link once a filter is active, and three groups:

| Group                 | Options                                                                             |
| --------------------- | ----------------------------------------------------------------------------------- |
| **Toolkit type**      | **All tools**, **App toolkits**, **Custom toolkits**. Each chip shows its count.    |
| **Connection status** | **Connected**, **Not connected**, **Pending**, **Expired**, **Error**, **Revoked**. |
| **Sort by**           | **Newest first** (default), **Oldest first**, **Name A–Z**, **Name Z–A**.           |

### The Delete connection dialog

<Warning>
  Deleting a connection breaks every agent that uses it, and the deletion cannot be undone. Check the **Used by** card on the toolkit detail page first.
</Warning>

Two controls open the dialog. The trash icon on the **Connected** tab card opens **Delete connection**. The **Delete Connection** button in the **Danger Zone** card on the toolkit detail page opens **Delete {"{toolkit name}"} connection?**. Both cards are shown to organization admins only.

The dialog names the connection and repeats the consequence. Select **Delete** to confirm, or **Cancel**.

### The actions modal

**View {"{n}"} actions** opens a modal titled with the toolkit name and **Actions**. It lists every action with its name, tags, and description. An **Important** badge marks the actions the provider highlights.

The footer counts the actions available. Select **Close**, or **Add Tool** to continue to the **Add Tool** modal.

<Frame>
  <img src={img.tools.viewActionsModal} alt="The Gmail Actions modal listing actions with Important badges, tags, and descriptions, with a footer showing the action count and Close and Add Tool buttons" />
</Frame>

## Related pages

* [Enable and use actions](/docs/guides/tools/enable-and-use-actions)
* [CodeKit overview](/docs/guides/tools/codekit-overview)
* [Write a custom action](/docs/guides/tools/write-a-custom-action)
