# Assistant Tools

Tools extend assistant capabilities by allowing them to perform actions, access external data, and integrate with third-party services. Freddy supports three types of tools: System Tools, MCP Tools, and Streamline Automations.

## Tool Types

### 1. System Tools (Built-in)

Native capabilities provided by Freddy:

- **File Search**: Semantic search across uploaded files
- **Web Search**: Real-time internet search
- **Code Interpreter**: Execute Python code safely


### 2. MCP Tools (Integrations)

Custom integrations via Model Context Protocol:

- **Custom MCPs**: User-configured MCP servers
- **Personal Connectors**: OAuth-based third-party integrations (Google Drive, Notion, etc.)
- **Streamline Automations**: Workflow automation tools


### 3. Streamline Tools

Automations created in the Streamline platform that expose MCP interfaces.

## Tool Configuration Structure

Tools are configured in the `assistant_tool_configurations` table:


```json
{
  "system_tools": {
    "file_search": {
      "enabled": true,
      "max_results": 10,
      "min_relevance_score": 0.7
    },
    "web_search": {
      "enabled": true,
      "safe_mode": true,
      "max_results": 5
    },
    "code_interpreter": {
      "enabled": false
    }
  },
  "mcp_tools": [
    "mcp_abc123",  // Custom MCP server
    "mcp_def456",  // Google Drive connector
    "mcp_ghi789"   // GitHub integration
  ],
  "streamline_tools": [
    "sauto_xyz789"  // Streamline automation
  ]
}
```

## System Tools

### File Search

Enable semantic search across files attached to the assistant.

**Configuration:**


```json
{
  "file_search": {
    "enabled": true,
    "max_results": 10,
    "min_relevance_score": 0.7,
    "search_mode": "hybrid"  // "semantic", "keyword", "hybrid"
  }
}
```

**Use Case:**


```
User: "What does our refund policy say about damaged items?"
Assistant: [Searches attached policy documents]
          "According to section 3.2 of the refund policy..."
```

**Requirements:**

- Vector store attached to assistant
- Files uploaded and indexed


### Web Search

Real-time internet search for current information.

**Configuration:**


```json
{
  "web_search": {
    "enabled": true,
    "safe_mode": true,
    "max_results": 5,
    "allowed_domains": ["example.com", "docs.example.com"]
  }
}
```

**Use Case:**


```
User: "What's the current price of Bitcoin?"
Assistant: [Searches web]
          "As of today, Bitcoin is trading at $43,250..."
```

**Safety:**

- Safe mode filters inappropriate content
- Domain restrictions for enterprise use
- Rate limiting to prevent abuse


### Code Interpreter

Execute Python code in a sandboxed environment.

**Configuration:**


```json
{
  "code_interpreter": {
    "enabled": true,
    "timeout_seconds": 30,
    "max_memory_mb": 512,
    "allowed_packages": ["pandas", "numpy", "matplotlib"]
  }
}
```

**Use Case:**


```
User: "Analyze this CSV and create a chart"
Assistant: [Executes Python code]
          "I've analyzed the data. Here's a summary:
           - Total rows: 1,234
           - Average value: 45.67
           [Chart attached]"
```

**Security:**

- Sandboxed execution environment
- Resource limits (CPU, memory, time)
- No network access from code
- File system isolation


## MCP Tools

### Custom MCP Servers

User-configured MCP servers for custom integrations.

**Setup:**


```bash
# 1. Create MCP configuration
curl https://api.aitronos.com/v1/mcp-configurations \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -d '{
    "name": "My Custom Tool",
    "type": "custom",
    "server_url": "https://my-mcp-server.com",
    "transport_type": "sse",
    "auth_type": "bearer_token",
    "credentials": {
      "token": "my-secret-token"
    }
  }'

# 2. Assign to assistant
curl https://api.aitronos.com/v1/assistants/{assistant_id}/tools \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -d '{
    "mcp_tools": ["mcp_abc123"]
  }'
```

**Configuration:**


```json
{
  "id": "mcp_abc123",
  "name": "Database Query Tool",
  "type": "custom",
  "server_url": "https://db-mcp.example.com",
  "transport_type": "sse",
  "auth_type": "bearer_token",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["query", "schema"]  // Restrict specific tools
  }
}
```

### Personal Connectors

OAuth-based integrations with third-party services.

**Supported Connectors:**

- Google Drive
- Notion
- GitHub
- Slack
- More coming soon...


**Setup Flow:**


```bash
# 1. Initiate OAuth flow
curl https://api.aitronos.com/v1/personal-connectors/google-drive/authorize \
  -H "X-API-Key: $FREDDY_API_KEY"

# Response includes authorization URL
{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

# 2. User authorizes (redirects back with code)

# 3. Complete OAuth flow
curl https://api.aitronos.com/v1/personal-connectors/google-drive/callback \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -d '{
    "code": "authorization_code_from_google"
  }'

# 4. Assign to assistant
curl https://api.aitronos.com/v1/assistants/{assistant_id}/tools \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -d '{
    "mcp_tools": ["mcp_google_drive_123"]
  }'
```

**Use Case:**


```
User: "Summarize the latest document in my Google Drive"
Assistant: [Accesses Google Drive via OAuth]
          "I found 'Q4 Report.docx' updated 2 hours ago.
           Here's a summary: ..."
```

### Streamline Automations

Workflow automations that expose MCP interfaces.

**Setup:**


```bash
# Streamline automations are registered automatically
# when created in the Streamline platform

# Assign to assistant
curl https://api.aitronos.com/v1/assistants/{assistant_id}/tools \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -d '{
    "streamline_tools": ["sauto_xyz789"]
  }'
```

**Use Case:**


```
User: "Create a new customer record for John Doe"
Assistant: [Triggers Streamline automation]
          "I've created a customer record with ID #12345
           and sent a welcome email."
```

## Tool Execution Flow

### 1. User Request


```
User: "Search our knowledge base for pricing info"
```

### 2. Assistant Analyzes Request


```
Assistant determines: Need to use file_search tool
```

### 3. Tool Invocation


```json
{
  "tool": "file_search",
  "parameters": {
    "query": "pricing information",
    "max_results": 5
  }
}
```

### 4. Tool Execution


```
System executes file_search:
- Searches vector store
- Returns relevant documents
```

### 5. Assistant Processes Results


```
Assistant: "Based on our pricing documentation:
           - Standard plan: $49/month
           - Professional plan: $99/month
           - Enterprise: Custom pricing"
```

## Tool Permissions

### Organization-Level Tools

Available to all users in the organization:


```json
{
  "mcp_configuration_id": "mcp_abc123",
  "organization_id": "org_xyz789",
  "user_id": null,  // null = org-wide
  "is_active": true
}
```

### User-Level Tools

Available only to specific users:


```json
{
  "mcp_configuration_id": "mcp_def456",
  "organization_id": "org_xyz789",
  "user_id": "usr_abc123",  // Specific user
  "is_active": true
}
```

### Tool Merging

When a user uses an assistant:


```
Active Tools = Assistant Tools + User Personal Tools
```

**Example:**


```
Assistant has:
- file_search (system)
- company_database (org MCP)

User has:
- google_drive (personal connector)
- notion (personal connector)

User sees all 4 tools when using this assistant
```

## Tool Configuration API

### Get Assistant Tools


```bash
GET /v1/assistants/{assistant_id}/tools
```

**Response:**


```json
{
  "system_tools": {
    "file_search": {"enabled": true},
    "web_search": {"enabled": false},
    "code_interpreter": {"enabled": false}
  },
  "mcp_tools": [
    {
      "id": "mcp_abc123",
      "name": "Database Tool",
      "type": "custom",
      "is_active": true
    }
  ],
  "streamline_tools": [
    {
      "id": "sauto_xyz789",
      "name": "Customer Onboarding",
      "is_active": true
    }
  ]
}
```

### Update Assistant Tools


```bash
PATCH /v1/assistants/{assistant_id}/tools
```

**Request:**


```json
{
  "system_tools": {
    "file_search": {
      "enabled": true,
      "max_results": 15
    },
    "web_search": {
      "enabled": true
    }
  },
  "mcp_tools": ["mcp_abc123", "mcp_def456"],
  "streamline_tools": ["sauto_xyz789"]
}
```

### Add MCP Tool


```bash
POST /v1/assistants/{assistant_id}/tools/mcp
```

**Request:**


```json
{
  "mcp_configuration_id": "mcp_new123"
}
```

### Remove MCP Tool


```bash
DELETE /v1/assistants/{assistant_id}/tools/mcp/{mcp_id}
```

## Best Practices

### ✅ DO

- **Enable only needed tools** to reduce complexity
- **Test tools individually** before combining
- **Set appropriate timeouts** for long-running operations
- **Use tool restrictions** to limit scope
- **Monitor tool usage** for performance and costs


### ❌ DON'T

- **Don't enable all tools** by default
- **Don't expose sensitive tools** to public assistants
- **Don't skip error handling** in tool configurations
- **Don't ignore rate limits** on external APIs
- **Don't forget to refresh OAuth tokens** for personal connectors


## Troubleshooting

### Tool Not Available

**Problem:** Tool doesn't appear in assistant responses

**Solutions:**

1. Check tool is enabled in configuration
2. Verify MCP configuration is active
3. Check user has access to personal connector
4. Ensure OAuth token is valid


### Tool Execution Fails

**Problem:** Tool executes but returns errors

**Solutions:**

1. Check tool configuration parameters
2. Verify API credentials are valid
3. Check rate limits on external services
4. Review tool logs for specific errors


### Slow Tool Responses

**Problem:** Tools take too long to respond

**Solutions:**

1. Reduce `max_results` for search tools
2. Add timeout limits
3. Cache frequently accessed data
4. Use async tool execution


## Related Documentation

- [Assistants Overview](/docs/documentation/assistants/overview)
- [Database Schema](/docs/documentation/assistants/database-schema)
- [MCP Tools Guide](/docs/documentation/core-concepts/mcp-tools)
- [System Tools Guide](/docs/documentation/system-tools)
- [Personal Connectors](/docs/documentation/personal-connectors/overview)