​
Giving Agents Tools

Tools transform agents from thinkers into doers. They allow agents to search the web, read files, call APIs, execute code, and interact with external systems. Let’s explore how to give your agents superpowers.

​
Understanding Tools in Atlas

​
What are Tools?

Tools are capabilities that agents can invoke to:
  • 🌐 Access external information (web search, APIs)
  • 📁 Interact with files and databases
  • 🧮 Perform calculations and data processing
  • 🔧 Execute system commands
  • 🤝 Integrate with third-party services

​
Tool Types

  1. Built-in Tools - Provided by Atlas
  2. MCP Servers - Model Context Protocol tools
  3. Custom Tools - Your own implementations
  4. Remote Tools - External API integrations

​
Quick Start

Give an agent basic tools: 
agents:
  researcher:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    tools: ["web-search", "calculator", "file-reader"]
    prompts:
      system: |
        You are a research assistant with access to tools.
        Use them to find accurate, up-to-date information.

​
Built-in Tools

Atlas provides common tools out of the box: 
tools: ["web-search"]

# Agent can now search the internet
# Example: "Search for latest AI developments"

​
Calculator

tools: ["calculator"]

# Agent can perform calculations
# Example: "Calculate compound interest over 5 years"

​
File System

tools: ["file-reader", "file-writer"]

# Agent can read and write files
# Example: "Read data.csv and summarize contents"

​
Code Interpreter

tools: ["code-interpreter"]

# Agent can execute code
# Example: "Write and run Python code to analyze this data"

​
MCP (Model Context Protocol) Tools

MCP is Atlas’s standard for tool integration:

​
Basic MCP Configuration

tools:
  mcp:
    servers:
      # GitHub integration
      github:
        transport:
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-github"]
        env:
          GITHUB_TOKEN: "${GITHUB_TOKEN}"

​
Advanced MCP Setup

tools:
  mcp:
    # Global MCP settings
    client_config:
      timeout: "30s"
      retry_policy:
        max_attempts: 3
        backoff: "exponential"
    
    servers:
      # Filesystem MCP server
      filesystem:
        transport:
          type: "stdio"
          command: "mcp-filesystem"
          args: ["--root", "./data"]
        
        # Tool filtering
        tools:
          allow: ["read_file", "list_directory"]
          deny: ["delete_file"]  # Prevent deletions
        
        # Authentication
        auth:
          type: "bearer"
          token_env: "MCP_FS_TOKEN"
      
      # Database MCP server
      database:
        transport:
          type: "http"
          url: "http://localhost:8080/mcp"
        
        # Server-specific config
        config:
          connection_string: "${DATABASE_URL}"
          read_only: false
          max_query_time: "10s"

servers:
  # Slack integration
  slack:
    transport:
      type: "stdio"
      command: "mcp-slack-server"
    env:
      SLACK_TOKEN: "${SLACK_TOKEN}"
    tools:
      allow: ["send_message", "read_channel"]
  
  # SQL database
  postgres:
    transport:
      type: "stdio"
      command: "mcp-postgres"
    config:
      connection: "${DATABASE_URL}"
      ssl: true
  
  # Web scraping
  browser:
    transport:
      type: "stdio"
      command: "mcp-browser"
    config:
      headless: true
      timeout: "30s"
  
  # AWS integration
  aws:
    transport:
      type: "stdio"
      command: "mcp-aws"
    env:
      AWS_REGION: "us-east-1"
      AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
      AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"

​
Tool Usage Patterns

​
1. Research Assistant

Combine search and analysis tools: 
agents:
  researcher:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    tools: ["web-search", "calculator", "file-writer"]
    
    prompts:
      system: |
        You are a research assistant. When given a topic:
        1. Search for current information
        2. Verify facts from multiple sources
        3. Calculate any relevant statistics
        4. Save findings to a markdown file
        
        Always cite sources and show calculations.

jobs:
  research-task:
    execution:
      agents:
        - id: "researcher"
          task: "Research {topic} and create a report"

​
2. Data Analyst

File processing and visualization: 
agents:
  analyst:
    type: "llm"
    tools: 
      - "file-reader"
      - "code-interpreter"
      - "chart-generator"
    
    prompts:
      system: |
        Analyze data files by:
        1. Reading the file to understand structure
        2. Using Python to process and analyze
        3. Creating visualizations
        4. Summarizing key findings

tools:
  mcp:
    servers:
      chart-generator:
        transport:
          type: "stdio"
          command: "mcp-charts"
        config:
          output_format: "png"
          style: "professional"

​
3. DevOps Assistant

System management tools: 
agents:
  devops:
    type: "llm"
    tools: ["terminal", "file-system", "docker", "kubernetes"]
    
    prompts:
      system: |
        You are a DevOps engineer. You can:
        - Run shell commands (be careful!)
        - Manage Docker containers
        - Interact with Kubernetes
        - Read and modify config files
        
        Always explain actions before executing.
        Never run destructive commands without confirmation.

tools:
  mcp:
    servers:
      terminal:
        transport:
          type: "stdio"
          command: "mcp-shell"
        config:
          shell: "bash"
          working_dir: "/app"
          allowed_commands: ["ls", "cat", "grep", "docker", "kubectl"]
          forbidden_patterns: ["rm -rf", "format", "delete"]

​
4. API Integration Specialist

External service integration: 
agents:
  api-integrator:
    type: "llm"
    tools: ["http-client", "json-parser", "oauth-handler"]
    
    prompts:
      system: |
        You integrate with external APIs:
        1. Handle authentication (OAuth, API keys)
        2. Make appropriate HTTP requests
        3. Parse and transform responses
        4. Handle errors gracefully

tools:
  mcp:
    servers:
      http-client:
        transport:
          type: "stdio"
          command: "mcp-http"
        config:
          rate_limit: "100/minute"
          timeout: "30s"
          follow_redirects: true
          
      oauth-handler:
        transport:
          type: "stdio"
          command: "mcp-oauth"
        config:
          providers:
            - name: "google"
              client_id: "${GOOGLE_CLIENT_ID}"
              client_secret: "${GOOGLE_CLIENT_SECRET}"

​
Tool Configuration

​
Tool Selection Strategy

Control how agents choose tools: 
agents:
  smart-agent:
    type: "llm"
    tools: ["web-search", "calculator", "file-reader"]
    
    config:
      # Automatic tool selection (default)
      tool_choice: "auto"
      
      # Force tool usage
      # tool_choice: "required"
      
      # Disable tools temporarily
      # tool_choice: "none"
      
      # Force specific tool
      # tool_choice: {"name": "web-search"}
      
      # Tool usage hints
      tool_preferences:
        calculation: "calculator"
        research: "web-search"
        data: "file-reader"

​
Tool Permissions

Restrict tool access for safety: 
tools:
  mcp:
    servers:
      filesystem:
        transport:
          type: "stdio"
          command: "mcp-filesystem"
        
        # Granular permissions
        permissions:
          read: ["./data", "./configs"]
          write: ["./output"]
          execute: []  # No execution
          
        # Tool-level filtering
        tools:
          allow: 
            - "read_file"
            - "list_directory"
            - "create_file"
          deny:
            - "delete_file"
            - "move_file"

​
Tool Timeouts and Limits

Prevent runaway tool usage: 
tools:
  mcp:
    client_config:
      # Global timeout
      timeout: "30s"
      
      # Rate limiting
      rate_limits:
        requests_per_minute: 60
        concurrent_requests: 5
      
      # Resource limits
      resource_limits:
        max_file_size: "10MB"
        max_response_size: "1MB"
        max_execution_time: "60s"

​
Custom Tool Development

​
Creating an MCP Server

Basic MCP server structure: 
# my_mcp_server.py
from mcp import Server, Tool, ToolResult

server = Server("my-tools")

@server.tool(
    name="process_data",
    description="Process data with custom logic",
    parameters={
        "type": "object",
        "properties": {
            "data": {"type": "string"},
            "operation": {"type": "string"}
        },
        "required": ["data", "operation"]
    }
)
async def process_data(data: str, operation: str) -> ToolResult:
    # Your tool logic here
    result = perform_operation(data, operation)
    return ToolResult(success=True, data=result)

if __name__ == "__main__":
    server.run()

​
Integrating Custom Tools

tools:
  mcp:
    servers:
      custom-processor:
        transport:
          type: "stdio"
          command: "python"
          args: ["./tools/my_mcp_server.py"]
        
        # Tool documentation
        metadata:
          version: "1.0.0"
          author: "Your Name"
          description: "Custom data processing tools"

agents:
  processor:
    type: "llm"
    tools: ["custom-processor"]
    prompts:
      system: |
        Use the process_data tool for custom operations.
        Available operations: transform, analyze, summarize

​
Tool Orchestration

​
Sequential Tool Usage

Chain tools together: 
agents:
  pipeline-agent:
    type: "llm"
    tools: ["web-search", "file-writer", "email-sender"]
    
    prompts:
      system: |
        For research requests:
        1. Search for information (web-search)
        2. Save findings to file (file-writer)
        3. Email the report (email-sender)
        
        Execute tools in sequence, using output from
        each step as input for the next.

​
Parallel Tool Usage

Use multiple tools simultaneously: 
agents:
  multi-tool-agent:
    type: "llm"
    tools: ["api-1", "api-2", "api-3"]
    
    config:
      parallel_tool_calls: true
      max_parallel_calls: 3
    
    prompts:
      system: |
        When gathering data from multiple sources:
        - Call APIs in parallel for efficiency
        - Combine results intelligently
        - Handle partial failures gracefully

​
Conditional Tool Usage

Use tools based on context: 
agents:
  adaptive-agent:
    type: "llm"
    tools: ["quick-search", "deep-search", "expert-system"]
    
    prompts:
      system: |
        Choose tools based on query complexity:
        - Simple questions: use quick-search
        - Research tasks: use deep-search
        - Technical problems: use expert-system
        
        Explain your tool choice before using.

​
Best Practices

​
1. Tool Selection

Choose minimal tool sets: 
# Good: Focused tools
tools: ["file-reader", "json-parser"]

# Avoid: Too many options
tools: ["tool1", "tool2", "tool3", "tool4", "tool5", ...]

​
2. Clear Documentation

Document tool usage in prompts: 
prompts:
  system: |
    Available tools and their uses:
    - web-search: Find current information online
    - calculator: Perform precise calculations
    - file-reader: Access local data files
    
    Always explain which tool you're using and why.

​
3. Error Handling

Plan for tool failures: 
prompts:
  system: |
    If a tool fails:
    1. Explain what went wrong
    2. Try alternative approaches
    3. Ask for clarification if needed
    4. Never claim false results

​
4. Security First

Restrict dangerous operations: 
tools:
  mcp:
    # Global security policy
    security:
      forbidden_operations: ["delete", "drop", "truncate"]
      require_confirmation: ["write", "update", "create"]
      audit_log: true

​
5. Performance Optimization

Cache tool results: 
tools:
  mcp:
    client_config:
      cache:
        enabled: true
        ttl: "300s"
        max_size: "100MB"
        cache_keys: ["url", "query", "parameters"]

​
Troubleshooting

​
Common Issues

Tool not found: 
# Check tool name matches exactly
tools: ["web-search"]  # not "websearch" or "web_search"
Permission denied: 
# Ensure proper permissions
permissions:
  allow_net: ["*"]  # or specific domains
  allow_read: ["./data"]
Timeout errors: 
# Increase timeout for slow tools
client_config:
  timeout: "60s"  # Increase from default 30s
Rate limiting: 
# Add delays between calls
config:
  tool_call_delay: "1s"
  rate_limit_retry: true

​
Advanced Examples

​
Multi-Step Research Agent

agents:
  advanced-researcher:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    
    tools:
      mcp:
        servers:
          web-search:
            transport:
              type: "stdio"
              command: "mcp-search"
            config:
              search_depth: "comprehensive"
              
          analyzer:
            transport:
              type: "stdio"
              command: "mcp-analyzer"
              
          report-builder:
            transport:
              type: "stdio"
              command: "mcp-reports"
    
    prompts:
      system: |
        You are an advanced research system. For each query:
        
        Phase 1: Discovery
        - Use web-search to find initial sources
        - Identify key themes and questions
        
        Phase 2: Deep Dive
        - Use analyzer to extract insights
        - Cross-reference multiple sources
        
        Phase 3: Synthesis
        - Use report-builder to create output
        - Include citations and confidence levels
        
        Always show your research process.

​
Integration Hub Agent

agents:
  integration-hub:
    type: "llm"
    
    tools:
      mcp:
        servers:
          # CRM Integration
          salesforce:
            transport:
              type: "http"
              url: "${SALESFORCE_MCP_URL}"
              
          # Communication
          slack:
            transport:
              type: "stdio"
              command: "mcp-slack"
              
          # Project Management
          jira:
            transport:
              type: "stdio"
              command: "mcp-jira"
              
          # Analytics
          analytics:
            transport:
              type: "http"
              url: "${ANALYTICS_API}/mcp"
    
    prompts:
      system: |
        You coordinate between multiple systems:
        
        Customer Updates:
        1. Check Salesforce for customer data
        2. Update Jira tickets as needed
        3. Notify team via Slack
        4. Log metrics to analytics
        
        Maintain data consistency across all systems.

​
Next Steps