fix: improve task assignment and equipment dispatch validation

- Make worker_id optional in assign_task to allow queued tasks
- Fix parameter validation to allow None for optional parameters
- Update business rules validation to skip None values
- Improve error handling for equipment dispatch workflow
- Update documentation page guardrails section with accurate info

Author: T-DevH

src/api/agents/operations/action_tools.py

@@ -316,21 +316,34 @@ async def create_task(
     async def assign_task(
         self,
         task_id: str,
-        worker_id: str,
+        worker_id: Optional[str] = None,
         assignment_type: str = "manual",
     ) -> Dict[str, Any]:
         """
         Assign a task to a worker.
 
         Args:
             task_id: Task ID to assign
-            worker_id: Worker ID to assign task to
+            worker_id: Worker ID to assign task to (optional - if None, task remains unassigned)
             assignment_type: Type of assignment (manual, automatic)
 
         Returns:
             Dict with assignment result
         """
         try:
+            # If no worker_id provided, skip assignment but return success
+            # Task will remain in 'queued' status until manually assigned
+            if not worker_id:
+                logger.info(f"Task {task_id} created but not assigned (no worker_id provided). Task is queued and ready for assignment.")
+                return {
+                    "success": True,
+                    "task_id": task_id,
+                    "worker_id": None,
+                    "assignment_type": assignment_type,
+                    "status": "queued",
+                    "message": "Task created successfully but not assigned. Please assign a worker manually or specify worker_id.",
+                }
+
             if not self.wms_service:
                 await self.initialize()
 
@@ -349,11 +362,14 @@ async def assign_task(
                     "status": "assigned",
                 }
             else:
+                error_msg = result.get("error", "Failed to update work queue entry") if result else "Failed to update work queue entry"
+                logger.warning(f"Failed to assign task {task_id} to worker {worker_id}: {error_msg}")
                 return {
                     "success": False,
                     "task_id": task_id,
                     "worker_id": worker_id,
-                    "error": "Failed to update work queue entry",
+                    "error": error_msg,
+                    "status": "queued",  # Task remains queued if assignment fails
                 }
         except Exception as e:
             logger.error(f"Failed to assign task: {e}")
@@ -362,6 +378,7 @@ async def assign_task(
                 "task_id": task_id,
                 "worker_id": worker_id,
                 "error": str(e),
+                "status": "queued",  # Task remains queued if assignment fails
             }
 
     async def get_task_status(

src/api/agents/operations/mcp_operations_agent.py

@@ -857,6 +857,41 @@ async def execute_single_tool(step: Dict[str, Any], previous_results: Dict[str,
                     if dep_result:
                         break  # Found the dependency, no need to check others
 
+            # Skip tool execution if required parameters are missing
+            if tool_name == "assign_task" and (arguments.get("task_id") is None or arguments.get("task_id") == "None"):
+                logger.warning(f"Skipping {tool_name} - task_id is required but not provided")
+                result_dict = {
+                    "tool_name": tool_name,
+                    "success": False,
+                    "error": "task_id is required but not provided",
+                    "execution_time": datetime.utcnow().isoformat(),
+                }
+                return (tool_id, result_dict)
+            
+            if tool_name == "assign_task" and (arguments.get("worker_id") is None or arguments.get("worker_id") == "None"):
+                logger.info(f"Executing {tool_name} without worker_id - task will remain queued")
+                # Continue execution - the tool will handle None worker_id gracefully
+            
+            if tool_name in ["assign_equipment", "dispatch_equipment"]:
+                if arguments.get("task_id") is None or arguments.get("task_id") == "None":
+                    logger.warning(f"Skipping {tool_name} - task_id is required but not provided")
+                    result_dict = {
+                        "tool_name": tool_name,
+                        "success": False,
+                        "error": "task_id is required but not provided (should come from create_task result)",
+                        "execution_time": datetime.utcnow().isoformat(),
+                    }
+                    return (tool_id, result_dict)
+                if arguments.get("asset_id") is None or arguments.get("asset_id") == "None":
+                    logger.warning(f"Skipping {tool_name} - asset_id is required but not provided (should come from get_equipment_status result)")
+                    result_dict = {
+                        "tool_name": tool_name,
+                        "success": False,
+                        "error": "asset_id is required but not provided (should come from get_equipment_status result)",
+                        "execution_time": datetime.utcnow().isoformat(),
+                    }
+                    return (tool_id, result_dict)
+
             try:
                 logger.info(
                     f"Executing MCP tool: {tool_name} with arguments: {arguments}"

src/api/services/mcp/adapters/operations_adapter.py

@@ -137,22 +137,22 @@ async def _register_tools(self) -> None:
         # Register assign_task tool
         self.tools["assign_task"] = MCPTool(
             name="assign_task",
-            description="Assign a task to a worker",
+            description="Assign a task to a worker. If worker_id is not provided, task will remain queued for manual assignment.",
             tool_type=MCPToolType.FUNCTION,
             parameters={
                 "type": "object",
                 "properties": {
                     "task_id": {"type": "string", "description": "Task ID to assign"},
                     "worker_id": {
                         "type": "string",
-                        "description": "Worker ID to assign task to",
+                        "description": "Worker ID to assign task to (optional - if not provided, task remains queued)",
                     },
                     "assignment_type": {
                         "type": "string",
                         "description": "Type of assignment (manual, automatic)",
                     },
                 },
-                "required": ["task_id", "worker_id"],
+                "required": ["task_id"],  # worker_id is now optional
             },
             handler=self._handle_assign_task,
         )
@@ -231,9 +231,10 @@ async def _handle_create_task(self, arguments: Dict[str, Any]) -> Dict[str, Any]
     async def _handle_assign_task(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
         """Handle assign_task tool execution."""
         try:
+            # worker_id is now optional - if not provided, task will remain queued
             result = await self.operations_tools.assign_task(
                 task_id=arguments["task_id"],
-                worker_id=arguments["worker_id"],
+                worker_id=arguments.get("worker_id"),  # Optional - can be None
                 assignment_type=arguments.get("assignment_type", "manual"),
             )
             return result

src/api/services/mcp/parameter_validator.py

@@ -179,8 +179,16 @@ async def validate_tool_parameters(
             for param_name, param_value in arguments.items():
                 if param_name in properties:
                     param_schema = properties[param_name]
+                    is_required = param_name in required_params
+                    
+                    # Skip validation for None values of optional parameters
+                    # This allows tools like get_equipment_status to work with asset_id=None
+                    if param_value is None and not is_required:
+                        validated_arguments[param_name] = None
+                        continue
+                    
                     validation_result = await self._validate_parameter(
-                        param_name, param_value, param_schema, tool_name
+                        param_name, param_value, param_schema, tool_name, is_required
                     )
 
                     if validation_result["valid"]:
@@ -247,12 +255,18 @@ async def _validate_parameter(
         param_value: Any,
         param_schema: Dict[str, Any],
         tool_name: str,
+        is_required: bool = False,
     ) -> Dict[str, Any]:
         """Validate a single parameter."""
         try:
             # Get parameter type
             param_type = param_schema.get("type", "string")
 
+            # Allow None for optional parameters (not required)
+            # This allows tools to work with optional parameters like asset_id in get_equipment_status
+            if param_value is None and not is_required:
+                return {"valid": True, "value": None, "issue": None}
+
             # Type validation
             if not self._validate_type(param_value, param_type):
                 return {
@@ -268,32 +282,36 @@ async def _validate_parameter(
                     ),
                 }
 
-            # Format validation
-            if param_type == "string":
+            # Skip format/length/range validation for None values (already handled above)
+            if param_value is None:
+                return {"valid": True, "value": None, "issue": None}
+
+            # Format validation (skip if None - already handled above)
+            if param_type == "string" and param_value is not None:
                 format_validation = self._validate_string_format(
                     param_name, param_value, param_schema
                 )
                 if not format_validation["valid"]:
                     return format_validation
 
-            # Range validation
-            if param_type in ["integer", "number"]:
+            # Range validation (skip if None - already handled above)
+            if param_type in ["integer", "number"] and param_value is not None:
                 range_validation = self._validate_range(
                     param_name, param_value, param_schema
                 )
                 if not range_validation["valid"]:
                     return range_validation
 
-            # Length validation
-            if param_type == "string":
+            # Length validation (skip if None - already handled above)
+            if param_type == "string" and param_value is not None:
                 length_validation = self._validate_length(
                     param_name, param_value, param_schema
                 )
                 if not length_validation["valid"]:
                     return length_validation
 
-            # Enum validation
-            if "enum" in param_schema:
+            # Enum validation (skip if None - already handled above)
+            if "enum" in param_schema and param_value is not None:
                 enum_validation = self._validate_enum(
                     param_name, param_value, param_schema
                 )
@@ -496,8 +514,8 @@ async def _validate_equipment_business_rules(
         """Validate equipment-specific business rules."""
         issues = []
 
-        # Equipment ID format validation
-        if "asset_id" in arguments:
+        # Equipment ID format validation (skip if None - it's optional)
+        if "asset_id" in arguments and arguments["asset_id"] is not None:
             asset_id = arguments["asset_id"]
             if not self.validation_patterns[ParameterType.EQUIPMENT_ID.value].match(
                 asset_id
@@ -512,8 +530,8 @@ async def _validate_equipment_business_rules(
                     )
                 )
 
-        # Equipment status validation
-        if "status" in arguments:
+        # Equipment status validation (skip if None - it's optional)
+        if "status" in arguments and arguments["status"] is not None:
             status = arguments["status"]
             valid_statuses = self.business_rules["equipment_status"]["valid_values"]
             if status not in valid_statuses:
@@ -526,6 +544,22 @@ async def _validate_equipment_business_rules(
                         provided_value=status,
                     )
                 )
+        
+        # Equipment type validation (skip if None - it's optional, but if provided should be valid)
+        if "equipment_type" in arguments and arguments["equipment_type"] is not None:
+            equipment_type = arguments["equipment_type"]
+            if "equipment_type" in self.business_rules:
+                valid_types = self.business_rules["equipment_type"]["valid_values"]
+                if equipment_type not in valid_types:
+                    issues.append(
+                        ValidationIssue(
+                            parameter="equipment_type",
+                            level=ValidationLevel.WARNING,
+                            message=f"Equipment type '{equipment_type}' is not in standard list",
+                            suggestion=f"Valid types are: {', '.join(valid_types)}",
+                            provided_value=equipment_type,
+                        )
+                    )
 
         return issues
 
@@ -535,8 +569,8 @@ async def _validate_task_business_rules(
         """Validate task-specific business rules."""
         issues = []
 
-        # Task ID format validation
-        if "task_id" in arguments:
+        # Task ID format validation (skip if None - it's optional)
+        if "task_id" in arguments and arguments["task_id"] is not None:
             task_id = arguments["task_id"]
             if not self.validation_patterns[ParameterType.TASK_ID.value].match(task_id):
                 issues.append(