Tool Design & Implementation

# Inefficient: 5 separate tools
customer = await get_customer(email)
orders = await get_customer_orders(customer.id)
tickets = await get_customer_tickets(customer.id)
preferences = await get_customer_preferences(customer.id)
loyalty = await get_loyalty_status(customer.id)

# Result: 5 agent steps, high latency

@server.tool()
async def get_complete_customer_context(email: str) -> dict:
    """Get comprehensive customer information in one call.
    
    Returns customer profile, recent orders, open tickets, preferences,
    and loyalty status. Optimized for agent efficiency.
    """
    
    # Fetch in parallel internally
    customer, orders, tickets, prefs, loyalty = await asyncio.gather(
        customer_db.find(email),
        order_api.get_recent(email, limit=5),
        ticket_api.get_open(email),
        prefs_api.get(email),
        loyalty_api.get_status(email),
        return_exceptions=True
    )
    
    return {
        "success": True,
        "data": {
            "customer": {...},
            "recent_orders": [...],
            "open_tickets": [...],
            "preferences": {...},
            "loyalty_tier": "gold"
        },
        "error": None,
        "message": "Complete context retrieved"
    }

# Result: 1 agent step, lower latency

@server.tool()
async def get_order(order_id: str) -> dict:
    """Get order data."""
    order = await db.get(order_id)
    return {"order": order}  # Raw data

@server.tool()
async def get_order_with_context(order_id: str) -> dict:
    """Get order with helpful context for customer service.
    
    Returns order data plus computed insights that help you
    assist the customer effectively.
    """
    order = await db.get(order_id)
    
    # Add semantic enrichment
    days_since_order = (datetime.now() - order.created).days
    is_delayed = order.estimated_delivery < datetime.now()
    can_cancel = order.status in ["pending", "processing"]
    can_modify = order.status == "pending"
    
    return {
        "success": True,
        "data": {
            "order": {
                "id": order.id,
                "status": order.status,
                "total": order.total,
                "items": order.items
            },
            "context": {
                "days_since_order": days_since_order,
                "is_delayed": is_delayed,
                "delay_days": (datetime.now() - order.estimated_delivery).days if is_delayed else 0,
                "can_cancel": can_cancel,
                "can_modify": can_modify,
                "next_actions": self._suggest_actions(order)
            }
        },
        "error": None,
        "message": f"Order {order_id} retrieved with context"
    }
    
def _suggest_actions(self, order) -> list[str]:
    """Suggest what agent should offer customer."""
    actions = []
    
    if order.is_delayed:
        actions.append("offer_apology_for_delay")
        actions.append("provide_updated_delivery_estimate")
    
    if order.can_cancel:
        actions.append("offer_cancellation_option")
    
    if order.status == "delivered" and order.days_since_delivery < 30:
        actions.append("offer_return_if_unsatisfied")
    
    return actions

@server.tool()
async def send_email(
    to: str,
    subject: str,
    body: str
) -> dict:
    """Send email to customer.
    
    Handles errors gracefully and suggests alternatives.
    """
    
    # Validate email format
    if not re.match(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", to):
        return {
            "success": False,
            "data": None,
            "error": "invalid_email",
            "message": f"Invalid email format: {to}. Ask customer for correct email."
        }
    
    try:
        # Attempt to send
        result = await email_api.send(to, subject, body)
        
        return {
            "success": True,
            "data": {
                "message_id": result.id,
                "sent_at": result.timestamp
            },
            "error": None,
            "message": f"Email sent to {to}"
        }
        
    except RateLimitError:
        return {
            "success": False,
            "data": None,
            "error": "rate_limited",
            "message": "Email rate limit exceeded. Create ticket for human follow-up instead."
        }
    
    except SMTPError as e:
        return {
            "success": False,
            "data": None,
            "error": "smtp_error",
            "message": f"Email system unavailable. Alternative: Call customer at {get_customer_phone(to)}"
        }
    
    except Exception as e:
        return {
            "success": False,
            "data": None,
            "error": "unknown_error",
            "message": "Could not send email. Create support ticket for manual outreach."
        }