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

# Connecting Tools

> Configure tools and permissions for AI workers to enable powerful integrations

## Overview

Tools enable AI workers to perform actions and access external systems. Spinnable provides a comprehensive tool ecosystem with granular permission controls to ensure security while maximizing functionality.

## Key Concepts

### Worker-Level Configuration

Tools are configured at the **worker level**, not the team level. Each worker can have different tools enabled based on its specific role and responsibilities.

### Two-Level Permission System

Spinnable implements a two-tier permission architecture:

1. **Account-Level Permissions**: Team administrators grant broad access to integrated services (e.g., "this team can use GitHub")
2. **Worker-Level Permissions**: Individual workers receive granular permissions for specific operations (e.g., "this worker can read issues but not create them")

This separation ensures:

* Centralized security control at the account level
* Flexible, role-specific configurations at the worker level
* Clear audit trails for tool usage

## Available Tool Categories

<Info>
  For a complete list of all available tools and detailed documentation, see our [Tools & Integrations](/tools/overview) directory.
</Info>

### Communication Tools

* **Slack**: Send messages, manage channels, react to conversations
* **Email**: Send and receive emails through integrated accounts

### Development Tools

* **GitHub**: Manage repositories, issues, pull requests, and code reviews
* **GitLab**: Version control and CI/CD pipeline management
* **Jira**: Issue tracking and project management

### Productivity Tools

* **Google Workspace**: Access Gmail, Calendar, Drive, Docs, and Sheets
* **Microsoft 365**: Outlook, Calendar, OneDrive integration
* **Notion**: Database queries and page management

### Data & Analytics

* **SQL Databases**: Execute queries on connected databases
* **APIs**: Custom API integrations with authentication

### Knowledge Tools

* **Web Search**: Real-time internet search capabilities
* **Knowledge Base**: Access to your organization's documentation

## Configuring Tools for a Worker

### Step 1: Access Worker Settings

1. Navigate to **Workers**
2. Select the worker you want to configure
3. Click the **Tools** tab

### Step 2: Enable Required Tools

<Steps>
  <Step title="Select Tool Category">
    Choose from available tool categories based on account-level permissions
  </Step>

  <Step title="Configure Permissions">
    Set granular permissions for each tool:

    * **Read**: View data and retrieve information
    * **Write**: Create and update resources
    * **Delete**: Remove resources (use with caution)
  </Step>

  <Step title="Set Parameters">
    Configure tool-specific parameters:

    * API endpoints
    * Default repositories or projects
    * Rate limits
    * Timeout settings
  </Step>

  <Step title="Test Configuration">
    Use the built-in testing interface to verify tool access
  </Step>
</Steps>

### Step 3: Save and Deploy

Click **Save Changes** to apply the tool configuration. The worker will immediately have access to the newly configured tools.

## Permission Examples

### GitHub Read-Only Worker

```json theme={null}
{
  "tools": {
    "github": {
      "permissions": {
        "repositories": "read",
        "issues": "read",
        "pull_requests": "read",
        "code": "read"
      }
    }
  }
}
```

### Full-Access Development Worker

```json theme={null}
{
  "tools": {
    "github": {
      "permissions": {
        "repositories": "write",
        "issues": "write",
        "pull_requests": "write",
        "code": "write",
        "reviews": "write"
      }
    },
    "slack": {
      "permissions": {
        "messages": "write",
        "channels": "read"
      }
    }
  }
}
```

### Analytics Worker

```json theme={null}
{
  "tools": {
    "sql": {
      "permissions": {
        "query": "read"
      },
      "databases": ["analytics_db", "reporting_db"]
    },
    "google_sheets": {
      "permissions": {
        "read": true,
        "write": true
      }
    }
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Principle of Least Privilege">
    Grant only the minimum permissions necessary for a worker to perform its intended function. Start with read-only access and expand as needed.
  </Accordion>

  <Accordion title="Regular Permission Audits">
    Review worker tool permissions quarterly to ensure they align with current responsibilities. Remove unused tools to reduce security surface.
  </Accordion>

  <Accordion title="Separate Workers for Different Functions">
    Create specialized workers for distinct tasks rather than one worker with all permissions. For example:

    * **Support Worker**: Slack + Zendesk (read/write)
    * **Code Review Worker**: GitHub (read + comment)
    * **Deployment Worker**: GitHub + AWS (write)
  </Accordion>

  <Accordion title="Monitor Tool Usage">
    Use the Activity Log to track which tools workers are using and identify unusual patterns.
  </Accordion>

  <Accordion title="Test in Development First">
    Create a duplicate worker in a development environment to test tool configurations before deploying to production.
  </Accordion>
</AccordionGroup>

## Common Tool Workflows

### Automating GitHub Issue Triage

1. **Tools Needed**: GitHub (read issues, write labels, write comments)
2. **Configuration**: Enable GitHub tool with write permissions for labels and comments
3. **Worker Behavior**: Monitors new issues, categorizes them, adds appropriate labels, and posts initial responses

### Customer Support Automation

1. **Tools Needed**: Slack (read/write messages), Zendesk (read/write tickets), Knowledge Base (read)
2. **Configuration**: Connect all three tools with appropriate permissions
3. **Worker Behavior**: Receives Slack questions, searches knowledge base, creates Zendesk tickets for complex issues

### Documentation Sync

1. **Tools Needed**: GitHub (read code/comments), Notion (write pages), Slack (write messages)
2. **Configuration**: GitHub read access, Notion write access, Slack channel posting
3. **Worker Behavior**: Monitors code changes, updates documentation in Notion, notifies team via Slack

## Security Considerations

### API Key Management

* Spinnable securely stores all API keys and credentials
* Keys are encrypted at rest and in transit
* Workers never see or expose raw credentials

### Audit Logging

All tool actions are logged with:

* Timestamp
* Worker ID
* Tool and method used
* Success/failure status
* User context (if applicable)

### Rate Limiting

Configure rate limits per worker to prevent:

* Accidental API quota exhaustion
* Runaway automation loops
* Service degradation

### IP Whitelisting

For sensitive integrations, configure IP restrictions at the account level to ensure tools can only be accessed from approved networks.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool Not Appearing in Worker Settings">
    **Cause**: The tool hasn't been enabled at the account level.

    **Solution**: Contact your team administrator to enable the integration in Account Settings > Integrations.
  </Accordion>

  <Accordion title="Permission Denied Errors">
    **Cause**: Worker lacks specific permission for the attempted operation.

    **Solution**: Review worker tool permissions and add the required permission level (read/write/delete).
  </Accordion>

  <Accordion title="Tool Timeout Issues">
    **Cause**: External service responding slowly or network latency.

    **Solution**: Increase timeout values in tool settings or check service status page.
  </Accordion>

  <Accordion title="Authentication Failures">
    **Cause**: Expired or invalid credentials for the external service.

    **Solution**: Re-authenticate the integration in Account Settings > Integrations.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Tool Permissions" icon="plug" href="/concepts/tool-permissions">
    Learn about tool permissions and access control
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/tools/overview">
    See all available tools and integrations
  </Card>

  <Card title="Managing Workers" icon="robot" href="/guides/managing-workers">
    Configure workers and their tool access
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full API documentation for tool integrations
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Review Available Integrations">
    Check which tools are already connected at the account level
  </Step>

  <Step title="Plan Worker Roles">
    Map out which workers need which tools based on their responsibilities
  </Step>

  <Step title="Configure Tools">
    Enable and configure tools for each worker following the principle of least privilege
  </Step>

  <Step title="Test Thoroughly">
    Verify tool access and permissions before deploying to production
  </Step>

  <Step title="Monitor and Iterate">
    Use activity logs to optimize tool configurations over time
  </Step>
</Steps>