Tool Description Failures

class ToolDescriptionValidator:
    """Validate tool descriptions for voice agents"""
    
    QUALITY_CRITERIA = {
        "has_when_to_call": r"(use this|call this|when)",
        "has_purpose": r"(to|for|in order to)",
        "has_negative": r"(do not|don't|never|only)",
        "has_format_hint": r"(format|e\.g\.|example)",
    }
    
    PARAMETER_CRITERIA = {
        "has_description": lambda p: bool(p.get("description")),
        "has_format": lambda p: "format" in p.get("description", "").lower(),
        "has_example": lambda p: "e.g." in p.get("description", "") or 
                                 "example" in p.get("description", "").lower(),
    }
    
    def validate_tool(self, tool: dict) -> dict:
        """Validate a tool definition"""
        issues = []
        score = 0
        
        description = tool.get("description", "")
        
        # Check description quality
        if not description:
            issues.append({
                "type": "missing_description",
                "severity": "critical",
                "message": "Tool has no description"
            })
        else:
            for criterion, pattern in self.QUALITY_CRITERIA.items():
                if re.search(pattern, description, re.IGNORECASE):
                    score += 1
                else:
                    issues.append({
                        "type": f"missing_{criterion}",
                        "severity": "warning",
                        "message": f"Description lacks {criterion}"
                    })
        
        # Check parameters
        for param_name, param_def in tool.get("parameters", {}).items():
            for criterion, check in self.PARAMETER_CRITERIA.items():
                if not check(param_def):
                    issues.append({
                        "type": f"param_{criterion}",
                        "severity": "warning",
                        "parameter": param_name,
                        "message": f"Parameter '{param_name}' lacks {criterion}"
                    })
        
        # Check for common anti-patterns
        if tool.get("name", "").lower() in ["api_call", "call", "request"]:
            issues.append({
                "type": "generic_name",
                "severity": "error",
                "message": "Tool name is too generic"
            })
        
        return {
            "valid": len([i for i in issues if i["severity"] == "critical"]) == 0,
            "score": score,
            "max_score": len(self.QUALITY_CRITERIA),
            "issues": issues
        }
    
    def suggest_improvements(self, tool: dict) -> str:
        """Suggest improved tool description"""
        name = tool.get("name", "unknown_tool")
        current = tool.get("description", "")
        
        template = f"""
        Use this tool to [WHAT IT DOES]. 
        Call this when [WHEN TO CALL].
        Do NOT call this for [NEGATIVE CASES].
        
        Example: {name}(param1="value1", param2="value2")
        """
        
        return template


class ToolDefinitionBuilder:
    """Build well-structured tool definitions"""
    
    def build_tool(self, 
                   name: str,
                   purpose: str,
                   when_to_call: str,
                   when_not_to_call: str,
                   parameters: dict) -> dict:
        """Build a complete tool definition"""
        
        description = f"{purpose}. {when_to_call}. {when_not_to_call}"
        
        # Enhance parameters with format hints
        enhanced_params = {}
        for param_name, param_def in parameters.items():
            enhanced = param_def.copy()
            if "description" not in enhanced:
                enhanced["description"] = f"The {param_name} value"
            enhanced_params[param_name] = enhanced
        
        return {
            "name": name,
            "description": description,
            "parameters": enhanced_params
        }
    
    def build_transfer_tool(self, 
                            destinations: list,
                            triggers: list) -> dict:
        """Build transfer tool with explicit description"""
        
        dest_str = ", ".join(destinations)
        trigger_str = "; ".join(triggers)
        
        return {
            "name": "transferCall",
            "description": f"Transfer the caller to a human agent. "
                          f"Available destinations: {dest_str}. "
                          f"Use this when: {trigger_str}.",
            "parameters": {
                "destination": {
                    "type": "string",
                    "description": f"Where to transfer. Options: {dest_str}"
                },
                "reason": {
                    "type": "string",
                    "description": "Brief reason for transfer (for agent context)"
                }
            }
        }


# Example well-defined tools
EXAMPLE_TOOLS = [
    {
        "name": "get_available_slots",
        "description": "Use this tool to check for available appointment "
                      "times in the clinic's calendar for a specific date. "
                      "Call this BEFORE attempting to book so the caller "
                      "can choose a time. Do NOT call this if the caller "
                      "hasn't specified what service they need.",
        "parameters": {
            "date": {
                "type": "string",
                "description": "The date to check (format: YYYY-MM-DD, "
                              "e.g., 2026-05-29)"
            },
            "service_type": {
                "type": "string",
                "description": "Type of appointment: cleaning, checkup, "
                              "emergency, or consultation"
            },
            "location": {
                "type": "string",
                "description": "Clinic location (downtown, westside)"
            }
        }
    },
    {
        "name": "book_appointment",
        "description": "Use this tool to book a specific appointment slot "
                      "AFTER the caller has chosen a time from get_available_slots. "
                      "Do NOT call this without first checking availability. "
                      "Do NOT call this if you don't have the patient's name.",
        "parameters": {
            "slot_id": {
                "type": "string",
                "description": "The slot ID returned from get_available_slots"
            },
            "patient_name": {
                "type": "string",
                "description": "Full name of the patient (First Last)"
            },
            "contact_phone": {
                "type": "string",
                "description": "Phone number (format: +1XXXXXXXXXX)"
            }
        }
    }
]

tool_documentation: |
  ## Tool Best Practices
  
  Each tool description should include:
  1. WHAT it does (purpose)
  2. WHEN to call it (triggers)
  3. WHEN NOT to call it (negative conditions)
  4. Format hints for all parameters
  
  BAD tool description:
  "Makes an API call"
  
  GOOD tool description:
  "Use this tool to check for available appointment times 
   in the clinic's calendar for a specific date. Call this 
   BEFORE attempting to book so the caller can choose a time. 
   Do NOT call this if the caller hasn't specified what 
   service they need."
  
  TRANSFER TOOLS:
  Never leave transfer tool description empty. Include:
  - Available destinations
  - When to transfer (explicit triggers)
  - Example: "Transfer when caller asks for human, request 
    is outside scope, or you've failed twice to help."
  
  ATOMIC TOOLS:
  One tool = one action. Avoid combined tools like:
  BAD: appointment_action(mode="book|cancel|reschedule")
  GOOD: book_appointment, cancel_appointment, reschedule_appointment