Skip to content
/
Tool Configuration
Last updated

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:

{
  "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

Enable semantic search across files attached to the assistant.

Configuration:

{
  "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

Real-time internet search for current information.

Configuration:

{
  "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:

{
  "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:

# 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:

{
  "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:

# 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:

# 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

{
  "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:

{
  "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:

{
  "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

GET /v1/assistants/{assistant_id}/tools

Response:

{
  "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

PATCH /v1/assistants/{assistant_id}/tools

Request:

{
  "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

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

Request:

{
  "mcp_configuration_id": "mcp_new123"
}

Remove MCP Tool

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
Previous page
Next page