# FleetMind MCP Tools - Quick Reference

## Geocoding & Routing (3 tools)

1. **`geocode_address`** - Convert address to GPS coordinates
2. **`calculate_route`** - Calculate route with vehicle-specific optimization (motorcycle/car/bicycle), toll avoidance, traffic data
3. **`calculate_intelligent_route`** - Advanced routing with weather + traffic + vehicle type analysis

## Order Management (8 tools)

4. **`create_order`** - Create new delivery order with **MANDATORY expected_delivery_time** and SLA tracking
5. **`count_orders`** - Count orders by status (pending/assigned/in_transit/delivered)
6. **`fetch_orders`** - Get list of orders with filters and pagination
7. **`get_order_details`** - Get full details of specific order by ID including timing and SLA data
8. **`search_orders`** - Search orders by customer name, address, or order ID
9. **`get_incomplete_orders`** - Get all pending/assigned/in_transit orders
10. **`update_order`** - Update order status, driver, location, notes (with assignment cascading)
11. **`delete_order`** - Delete order (with active assignment checks)

## Driver Management (8 tools)

12. **`create_driver`** - Register new driver with name, phone, vehicle type
13. **`count_drivers`** - Count drivers by status (active/busy/offline)
14. **`fetch_drivers`** - Get list of drivers with filters and pagination
15. **`get_driver_details`** - Get full details of specific driver by ID
16. **`search_drivers`** - Search drivers by name, phone, or driver ID
17. **`get_available_drivers`** - Get all active drivers ready for assignment
18. **`update_driver`** - Update driver status, phone, vehicle type, location (with assignment validation)
19. **`delete_driver`** - Delete driver (with assignment safety checks)

## Assignment Management (8 tools)

20. **`create_assignment`** - Manually assign order to driver (validates status, calculates route, saves all data)
21. **`auto_assign_order`** - **AUTO ASSIGNMENT**: Automatically assign order to nearest driver meeting requirements (distance + validation based)
22. **`intelligent_assign_order`** - **AI ASSIGNMENT**: Use Google Gemini AI to intelligently select best driver based on all parameters with reasoning
23. **`get_assignment_details`** - Get assignment details by assignment ID, order ID, or driver ID
24. **`update_assignment`** - Update assignment status with cascading updates to orders/drivers
25. **`unassign_order`** - Unassign order from driver (reverts statuses, requires confirmation)
26. **`complete_delivery`** - Mark delivery complete and auto-update driver location to delivery address
27. **`fail_delivery`** - Mark delivery as failed with MANDATORY driver location and failure reason

## Bulk Operations (2 tools)

28. **`delete_all_orders`** - Bulk delete all orders (or by status filter, blocks if active assignments exist)
29. **`delete_all_drivers`** - Bulk delete all drivers (or by status filter, blocks if assignments exist)

---

## Total: 29 MCP Tools

**Routing Tools:** 3 (with Google Routes API integration)
**Order Tools:** 8 (full CRUD + search + cascading)
**Driver Tools:** 8 (full CRUD + search + cascading)
**Assignment Tools:** 8 (manual + auto + intelligent AI assignment + lifecycle management)
**Bulk Operations:** 2 (efficient mass deletions with safety checks)

### Key Features:
- ✅ Real-time traffic & weather-aware routing
- ✅ Vehicle-specific optimization (motorcycle/bicycle/car/van/truck)
- ✅ Toll detection & avoidance
- ✅ Complete fleet management (orders + drivers + assignments)
- ✅ **Three assignment methods: Manual, Auto (distance-based), and Intelligent (Gemini 2.0 AI)**
- ✅ **Auto assignment: nearest driver with capacity & skill validation**
- ✅ **Intelligent AI assignment: Gemini 2.0 Flash analyzes all parameters with detailed reasoning**
- ✅ Assignment system with automatic route calculation
- ✅ **Mandatory delivery deadline (expected_delivery_time) when creating orders**
- ✅ **Automatic SLA tracking with grace period**
- ✅ **Delivery performance status: on_time, late, very_late, failed_on_time, failed_late**
- ✅ **Automatic driver location updates on delivery completion**
- ✅ **Mandatory location + reason tracking for failed deliveries**
- ✅ **Structured failure reasons for analytics and reporting**
- ✅ Cascading status updates (order → assignment → driver)
- ✅ Safety checks preventing invalid deletions/updates
- ✅ PostgreSQL database with foreign key constraints
- ✅ Search & filtering capabilities
- ✅ Status tracking & validation

### Assignment System Capabilities:
- **Manual assignment** (`create_assignment`) - Manually assign order to specific driver
- **Auto assignment** (`auto_assign_order`) - Automatically assign to nearest driver meeting requirements:
  - Selects nearest driver by real-time route distance
  - Validates vehicle capacity (weight & volume)
  - Validates driver skills (fragile handling, cold storage)
  - Returns selection reason and distance info
- **Intelligent AI assignment** (`intelligent_assign_order`) - Gemini 2.0 Flash AI analyzes all parameters:
  - Uses latest Gemini 2.0 Flash model (gemini-2.0-flash-exp)
  - Evaluates order priority, fragility, time constraints, value
  - Considers driver location, capacity, skills, vehicle type
  - Analyzes real-time traffic, weather conditions
  - Evaluates complex tradeoffs (speed vs safety, cost vs quality)
  - Returns detailed AI reasoning and confidence score
  - Requires GOOGLE_API_KEY environment variable
- **Automatic route calculation** from driver location to delivery address
- **Delivery completion** with automatic driver location update to delivery address
- **SLA & Timing Tracking**:
  - Mandatory `expected_delivery_time` when creating orders
  - Automatic comparison of actual vs expected delivery time
  - Grace period support (default: 15 minutes)
  - Performance statuses: `on_time`, `late` (within grace), `very_late` (SLA violation)
  - `delivered_at` field automatically populated on completion/failure
- **Delivery failure handling** with mandatory GPS location and failure reason
- **Failure timing tracking**: `failed_on_time` vs `failed_late` status
- **Structured failure reasons**: customer_not_available, wrong_address, refused_delivery, damaged_goods, payment_issue, vehicle_breakdown, access_restricted, weather_conditions, other
- **Status management** with cascading updates across orders/drivers/assignments
- **Safety checks** preventing deletion of orders/drivers with active assignments
- **Assignment lifecycle**: active → in_progress → completed/failed/cancelled
- **Database integrity** via FK constraints (ON DELETE CASCADE/RESTRICT/SET NULL)