botserver/docs/guides/tools-vs-bots.md

# Tools vs Bots: When to Use Each

**Chapter 4: Understanding the Difference Between Function Calls and AI Agents**

---

## Overview

General Bots provides two ways to extend your bot's capabilities:
- **TOOLs** - Simple functions with input/output
- **BOTs** - Intelligent AI agents that can reason and remember

Understanding when to use each is crucial for building efficient, cost-effective automation.

## Quick Comparison

| Feature | TOOL | BOT |
|---------|------|-----|
| **Purpose** | Data operations | Decision making |
| **Intelligence** | None (function) | Full LLM reasoning |
| **Speed** | Fast (10-100ms) | Slower (1-5 seconds) |
| **Cost** | Free | LLM tokens ($0.001-0.01) |
| **Input** | Structured data | Natural language |
| **Output** | Structured data | Conversational response |
| **Memory** | Stateless | Remembers context |

## Tools: The Function Approach

### What Are Tools?

Tools are **stateless functions** that perform specific operations:

```basic
' Tool usage - direct function call
USE TOOL "check-order"
result = CALL TOOL "check-order" WITH order_id="12345"
' Returns: {"status": "delivered", "amount": 899}
```

### When to Use Tools

✅ **Perfect for:**
- Database queries
- API calls  
- Calculations
- Data transformations
- Real-time operations

```basic
' Examples of good tool usage
USE TOOL "get-weather"
weather = CALL TOOL "get-weather" WITH city="São Paulo"

USE TOOL "calculate-tax"
tax = CALL TOOL "calculate-tax" WITH amount=100, region="BR"

USE TOOL "send-email"
CALL TOOL "send-email" WITH to="user@example.com", subject="Order Confirmed"
```

### Tool Limitations

❌ **Cannot:**
- Make decisions
- Understand context
- Remember previous calls
- Handle ambiguous input
- Provide explanations

## Bots: The AI Agent Approach

### What Are Bots?

Bots are **intelligent agents** that can reason, remember, and make decisions:

```basic
' Bot usage - conversational interaction
ADD BOT "order-specialist"
response = ASK BOT "order-specialist" ABOUT "Customer says order 12345 arrived damaged. What should we do?"
' Returns: Detailed analysis with reasoning and recommendation
```

### When to Use Bots

✅ **Perfect for:**
- Complex decision making
- Natural language understanding
- Multi-step reasoning
- Context-aware responses
- Customer service scenarios

```basic
' Examples of good bot usage
ADD BOT "financial-advisor"
advice = ASK BOT "financial-advisor" ABOUT "Customer wants refund after 60 days but threatens legal action"

ADD BOT "technical-support"  
solution = ASK BOT "technical-support" ABOUT "User can't login, tried password reset twice"

ADD BOT "content-moderator"
decision = ASK BOT "content-moderator" ABOUT "Review this user comment for policy violations"
```

### Bot Capabilities

✅ **Can:**
- Analyze complex situations
- Remember conversation history
- Use multiple tools internally
- Provide detailed explanations
- Handle edge cases

## Real-World Example: Order Processing

### Scenario
Customer contacts support: *"My laptop order #12345 arrived broken. I need this fixed immediately as I have a presentation tomorrow."*

### Tool-Only Approach (Limited)

```basic
' Simple but inflexible
USE TOOL "check-order"
order = CALL TOOL "check-order" WITH order_id="12345"

USE TOOL "check-warranty"  
warranty = CALL TOOL "check-warranty" WITH order_id="12345"

IF order.status = "delivered" AND warranty.valid = true THEN
  TALK "You're eligible for replacement"
ELSE
  TALK "Please contact manager"
END IF
```

**Problems:**
- No understanding of urgency ("presentation tomorrow")
- No consideration of customer history
- Rigid, rule-based responses
- Cannot handle edge cases

### Bot Approach (Intelligent)

```basic
' Intelligent and flexible
ADD BOT "support-specialist"
response = ASK BOT "support-specialist" ABOUT "Customer says laptop order #12345 arrived broken. They have presentation tomorrow and need immediate help."
```

**Bot's internal reasoning:**
1. Uses `check-order` tool → Order delivered 2 days ago, $1,299 laptop
2. Uses `check-warranty` tool → Premium warranty valid
3. Uses `customer-history` tool → VIP customer, 8 previous orders
4. **Analyzes urgency** → Presentation tomorrow = time-sensitive
5. **Considers options** → Replacement (2-day shipping) vs immediate refund for local purchase
6. **Makes recommendation** → "Given urgency and VIP status, authorize immediate refund so customer can buy locally, plus expedited replacement as backup"

## Hybrid Approach: Best of Both Worlds

**Recommended pattern: Bots use Tools internally**

```basic
' support-specialist.bas - Bot implementation
USE TOOL "check-order"
USE TOOL "check-warranty"
USE TOOL "customer-history"
USE TOOL "inventory-check"
USE KB "support-policies"

WHEN ASKED ABOUT order_issue DO
  ' Gather data using tools (fast, cheap)
  order = CALL TOOL "check-order" WITH order_id
  warranty = CALL TOOL "check-warranty" WITH order_id
  customer = CALL TOOL "customer-history" WITH customer_id
  
  ' Apply AI reasoning (intelligent, contextual)
  urgency = ANALYZE urgency FROM user_message
  customer_value = CALCULATE value FROM customer.total_orders
  
  IF urgency = "high" AND customer_value = "vip" THEN
    recommendation = "Expedited resolution with manager approval"
  ELSE IF warranty.type = "premium" THEN
    recommendation = "Standard replacement process"
  ELSE
    recommendation = "Store credit or repair option"
  END IF
  
  RETURN detailed_response WITH reasoning AND next_steps
END WHEN
```

## Performance Guidelines

### Tool Performance
- **Latency:** 10-100ms
- **Cost:** $0 (no LLM calls)
- **Throughput:** 1000+ operations/second
- **Use for:** High-frequency, simple operations

### Bot Performance  
- **Latency:** 1-5 seconds
- **Cost:** $0.001-0.01 per interaction
- **Throughput:** 10-100 interactions/second
- **Use for:** Complex, high-value decisions

## Decision Framework

### Use TOOL when:
1. **Operation is deterministic** - Same input always produces same output
2. **Speed is critical** - Real-time responses needed
3. **Cost matters** - High-frequency operations
4. **Data is structured** - Clear input/output format

### Use BOT when:
1. **Context matters** - Previous conversation affects response
2. **Reasoning required** - Multiple factors to consider
3. **Natural language input** - Ambiguous or conversational requests
4. **Edge cases exist** - Situations requiring judgment

### Use HYBRID when:
1. **Complex workflows** - Multiple steps with decision points
2. **Data + Intelligence** - Need both fast data access and smart reasoning
3. **Scalability important** - Balance cost and capability

## Common Patterns

### Pattern 1: Data Retrieval
```basic
' TOOL: Simple lookup
price = CALL TOOL "get-price" WITH product_id="laptop-123"

' BOT: Contextual pricing
ADD BOT "pricing-advisor"
quote = ASK BOT "pricing-advisor" ABOUT "Customer wants bulk discount for 50 laptops, they're a returning enterprise client"
```

### Pattern 2: Validation
```basic
' TOOL: Rule-based validation  
valid = CALL TOOL "validate-email" WITH email="user@domain.com"

' BOT: Contextual validation
ADD BOT "content-reviewer"
assessment = ASK BOT "content-reviewer" ABOUT "Is this product review appropriate for our family-friendly site?"
```

### Pattern 3: Workflow Orchestration
```basic
' Hybrid: Bot coordinates, tools execute
ORCHESTRATE WORKFLOW "order-processing"
  STEP 1: CALL TOOL "validate-payment" WITH payment_info
  STEP 2: BOT "fraud-detector" ANALYZES transaction_pattern  
  STEP 3: CALL TOOL "reserve-inventory" WITH product_id
  STEP 4: BOT "shipping-optimizer" SELECTS best_carrier
  STEP 5: CALL TOOL "send-confirmation" WITH order_details
END WORKFLOW
```

## Best Practices

### 1. Start Simple, Add Intelligence
```basic
' Phase 1: Tool-based (fast to implement)
result = CALL TOOL "process-refund" WITH order_id, amount

' Phase 2: Add bot intelligence (when complexity grows)
ADD BOT "refund-specialist"
decision = ASK BOT "refund-specialist" ABOUT "Customer wants refund but policy expired, they're threatening bad review"
```

### 2. Cache Bot Responses
```basic
' Expensive bot call
ADD BOT "product-recommender"
recommendations = ASK BOT "product-recommender" ABOUT "Best laptop for gaming under $1000"

' Cache result for similar queries
REMEMBER "gaming-laptop-under-1000" AS recommendations
```

### 3. Fallback Patterns
```basic
' Try bot first, fallback to tool
TRY
  response = ASK BOT "smart-assistant" ABOUT user_query
CATCH bot_error
  ' Fallback to simple tool
  response = CALL TOOL "keyword-search" WITH query=user_query
END TRY
```

## Summary

**Tools** are your **workhorses** - fast, reliable, cost-effective for data operations.

**Bots** are your **brain trust** - intelligent, contextual, perfect for complex decisions.

**Hybrid approach** gives you the best of both: use tools for speed and bots for intelligence.

Choose based on your specific needs:
- Need speed? → Tool
- Need intelligence? → Bot  
- Need both? → Bot that uses tools

The key is understanding that **tools and bots complement each other** - they're not competing solutions, but different tools for different jobs in your AI automation toolkit.

---

**Next:** [Chapter 5: Building Multi-Agent Workflows](workflows.md)