Address code review feedback: enhance sanitize_tools with better documentation, error handling, and type validation

- Add comprehensive docstring with Args, Returns, and Example sections
- Implement try-catch error handling with logging for unexpected scenarios
- Add stronger type validation for dictionary values
- Include logging for debugging when non-dict objects are filtered
- Add type annotations for better maintainability and IDE support
- Add parameterized tests for better coverage and organization
- Add performance tests for large datasets
- Add tests for invalid dict value types and error handling scenarios

Addresses feedback from joaomdmoura and mplachta on PR #3044

Co-Authored-By: João <joao@crewai.com>

docs/enterprise/features/integrations.mdx

@@ -124,7 +124,7 @@ from crewai_tools import CrewaiEnterpriseTools
 enterprise_tools = CrewaiEnterpriseTools(
     actions_list=["gmail_find_email"] # only gmail_find_email tool will be available
 )
-gmail_tool = enterprise_tools[0]
+gmail_tool = enterprise_tools["gmail_find_email"]
 
 gmail_agent = Agent(
     role="Gmail Manager",

docs/mcp/overview.mdx

@@ -85,6 +85,22 @@ with MCPServerAdapter(server_params) as mcp_tools:
 ```
 This general pattern shows how to integrate tools. For specific examples tailored to each transport, refer to the detailed guides below.
 
+## Filtering Tools
+
+```python
+with MCPServerAdapter(server_params) as mcp_tools:
+    print(f"Available tools: {[tool.name for tool in mcp_tools]}")
+
+    my_agent = Agent(
+        role="MCP Tool User",
+        goal="Utilize tools from an MCP server.",
+        backstory="I can connect to MCP servers and use their tools.",
+        tools=mcp_tools["tool_name"], # Pass the loaded tools to your agent
+        reasoning=True,
+        verbose=True
+    )
+    # ... rest of your crew setup ...
+```
 ## Explore MCP Integrations
 
 <CardGroup cols={2}>

src/crewai/utilities/agent_utils.py

@@ -476,7 +476,14 @@ def load_agent_from_repository(from_repository: str) -> Dict[str, Any]:
                     try:
                         module = importlib.import_module(tool["module"])
                         tool_class = getattr(module, tool["name"])
-                        attributes[key].append(tool_class())
+
+                        tool_value = tool_class(**tool["init_params"])
+
+                        if isinstance(tool_value, list):
+                            attributes[key].extend(tool_value)
+                        else:
+                            attributes[key].append(tool_value)
+
                     except Exception as e:
                         raise AgentRepositoryError(
                             f"Tool {tool['name']} could not be loaded: {e}"

src/crewai/utilities/events/llm_events.py

@@ -1,10 +1,13 @@
+import logging
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, Type
 
-from pydantic import BaseModel
+from pydantic import BaseModel, model_validator
 
 from crewai.utilities.events.base_events import BaseEvent
 
+logger = logging.getLogger(__name__)
+
 
 class LLMCallType(Enum):
     """Type of LLM call being made"""
@@ -27,6 +30,44 @@ class LLMCallStartedEvent(BaseEvent):
     callbacks: Optional[List[Any]] = None
     available_functions: Optional[Dict[str, Any]] = None
 
+    @model_validator(mode='before')
+    @classmethod
+    def sanitize_tools(cls: Type["LLMCallStartedEvent"], values: Any) -> Any:
+        """Sanitize tools list to only include dict objects, filtering out non-dict objects like TokenCalcHandler.
+        
+        Args:
+            values (dict): Input values dictionary containing tools and other event data.
+
+        Returns:
+            dict: Sanitized values with filtered tools list containing only valid dict objects.
+        
+        Example:
+            >>> from crewai.utilities.token_counter_callback import TokenCalcHandler
+            >>> from crewai.agents.agent_builder.utilities.base_token_process import TokenProcess
+            >>> token_handler = TokenCalcHandler(TokenProcess())
+            >>> tools = [{"name": "tool1"}, token_handler, {"name": "tool2"}]
+            >>> sanitized = cls.sanitize_tools({"tools": tools})
+            >>> # Expected: {"tools": [{"name": "tool1"}, {"name": "tool2"}]}
+        """
+        try:
+            if isinstance(values, dict) and 'tools' in values and values['tools'] is not None:
+                if isinstance(values['tools'], list):
+                    sanitized_tools = []
+                    for tool in values['tools']:
+                        if isinstance(tool, dict):
+                            if all(isinstance(v, (str, int, float, bool, dict, list, type(None))) for v in tool.values()):
+                                sanitized_tools.append(tool)
+                            else:
+                                logger.warning(f"Tool dict contains invalid value types: {tool}")
+                        else:
+                            logger.debug(f"Filtering out non-dict tool object: {type(tool).__name__}")
+                    
+                    values['tools'] = sanitized_tools
+        except Exception as e:
+            logger.warning(f"Error during tools sanitization: {e}")
+        
+        return values
+
 
 class LLMCallCompletedEvent(BaseEvent):
     """Event emitted when a LLM call completes"""

tests/agent_test.py

@@ -2099,7 +2099,7 @@ def mock_get_auth_token():
 
 @patch("crewai.cli.plus_api.PlusAPI.get_agent")
 def test_agent_from_repository(mock_get_agent, mock_get_auth_token):
-    from crewai_tools import SerperDevTool, XMLSearchTool
+    from crewai_tools import SerperDevTool, XMLSearchTool, CSVSearchTool, EnterpriseActionTool
 
     mock_get_response = MagicMock()
     mock_get_response.status_code = 200
@@ -2108,19 +2108,42 @@ def test_agent_from_repository(mock_get_agent, mock_get_auth_token):
         "goal": "test goal",
         "backstory": "test backstory",
         "tools": [
-            {"module": "crewai_tools", "name": "SerperDevTool"},
-            {"module": "crewai_tools", "name": "XMLSearchTool"},
+            {"module": "crewai_tools", "name": "SerperDevTool", "init_params": {"n_results": 30}},
+            {"module": "crewai_tools", "name": "XMLSearchTool", "init_params": {"summarize": True}},
+            {"module": "crewai_tools", "name": "CSVSearchTool", "init_params": {}},
+
+            # using a tools that returns a list of BaseTools
+            {"module": "crewai_tools", "name": "CrewaiEnterpriseTools", "init_params": {"actions_list": [], "enterprise_token": "test_key"}},
         ],
     }
     mock_get_agent.return_value = mock_get_response
-    agent = Agent(from_repository="test_agent")
+
+    tool_action = EnterpriseActionTool(
+        name="test_name",
+        description="test_description",
+        enterprise_action_token="test_token",
+        action_name="test_action_name",
+        action_schema={"test": "test"},
+    )
+
+    with patch("crewai_tools.CrewaiEnterpriseTools", return_value=[tool_action]):
+        agent = Agent(from_repository="test_agent")
 
     assert agent.role == "test role"
     assert agent.goal == "test goal"
     assert agent.backstory == "test backstory"
-    assert len(agent.tools) == 2
+    assert len(agent.tools) == 4
+
     assert isinstance(agent.tools[0], SerperDevTool)
+    assert agent.tools[0].n_results == 30
     assert isinstance(agent.tools[1], XMLSearchTool)
+    assert agent.tools[1].summarize
+
+    assert isinstance(agent.tools[2], CSVSearchTool)
+    assert not agent.tools[2].summarize
+
+    assert isinstance(agent.tools[3], EnterpriseActionTool)
+    assert agent.tools[3].name == "test_name"
 
 
 @patch("crewai.cli.plus_api.PlusAPI.get_agent")
@@ -2133,7 +2156,7 @@ def test_agent_from_repository_override_attributes(mock_get_agent, mock_get_auth
         "role": "test role",
         "goal": "test goal",
         "backstory": "test backstory",
-        "tools": [{"name": "SerperDevTool", "module": "crewai_tools"}],
+        "tools": [{"name": "SerperDevTool", "module": "crewai_tools", "init_params": {}}],
     }
     mock_get_agent.return_value = mock_get_response
     agent = Agent(from_repository="test_agent", role="Custom Role")

tests/utilities/events/test_llm_events_validation.py

@@ -0,0 +1,203 @@
+import pytest
+import logging
+from crewai.utilities.events.llm_events import LLMCallStartedEvent
+from crewai.utilities.token_counter_callback import TokenCalcHandler
+from crewai.agents.agent_builder.utilities.base_token_process import TokenProcess
+
+
+class TestLLMCallStartedEventValidation:
+    """Test cases for LLMCallStartedEvent validation and sanitization"""
+
+    def test_normal_dict_tools_work(self):
+        """Test that normal dict tools work correctly"""
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[{"name": "tool1"}, {"name": "tool2"}],
+            callbacks=None
+        )
+        assert event.tools == [{"name": "tool1"}, {"name": "tool2"}]
+        assert event.type == "llm_call_started"
+
+    def test_token_calc_handler_in_tools_filtered_out(self):
+        """Test that TokenCalcHandler objects in tools list are filtered out"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[{"name": "tool1"}, token_handler, {"name": "tool2"}],
+            callbacks=None
+        )
+        
+        assert event.tools == [{"name": "tool1"}, {"name": "tool2"}]
+        assert len(event.tools) == 2
+
+    def test_mixed_objects_in_tools_only_dicts_preserved(self):
+        """Test that only dict objects are preserved when mixed types are in tools"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[
+                {"name": "tool1"},
+                token_handler,
+                "string_tool",
+                {"name": "tool2"},
+                123,
+                {"name": "tool3"}
+            ],
+            callbacks=None
+        )
+        
+        assert event.tools == [{"name": "tool1"}, {"name": "tool2"}, {"name": "tool3"}]
+        assert len(event.tools) == 3
+
+    def test_empty_tools_list_handled(self):
+        """Test that empty tools list is handled correctly"""
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[],
+            callbacks=None
+        )
+        assert event.tools == []
+
+    def test_none_tools_handled(self):
+        """Test that None tools value is handled correctly"""
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=None,
+            callbacks=None
+        )
+        assert event.tools is None
+
+    def test_all_non_dict_tools_results_in_empty_list(self):
+        """Test that when all tools are non-dict objects, result is empty list"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[token_handler, "string_tool", 123, ["list_tool"]],
+            callbacks=None
+        )
+        
+        assert event.tools == []
+
+    def test_reproduction_case_from_issue_3043(self):
+        """Test the exact reproduction case from GitHub issue #3043"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[{"name": "tool1"}, token_handler],
+            callbacks=None
+        )
+        
+        assert event.tools == [{"name": "tool1"}]
+        assert len(event.tools) == 1
+
+    def test_callbacks_with_token_handler_still_work(self):
+        """Test that TokenCalcHandler in callbacks still works normally"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[{"name": "tool1"}],
+            callbacks=[token_handler]
+        )
+        
+        assert event.tools == [{"name": "tool1"}]
+        assert event.callbacks == [token_handler]
+
+    def test_string_messages_work(self):
+        """Test that string messages work with tool sanitization"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        event = LLMCallStartedEvent(
+            messages="test message",
+            tools=[{"name": "tool1"}, token_handler],
+            callbacks=None
+        )
+        
+        assert event.messages == "test message"
+        assert event.tools == [{"name": "tool1"}]
+
+    def test_available_functions_preserved(self):
+        """Test that available_functions are preserved during sanitization"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        available_funcs = {"func1": lambda x: x}
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[{"name": "tool1"}, token_handler],
+            callbacks=None,
+            available_functions=available_funcs
+        )
+        
+        assert event.tools == [{"name": "tool1"}]
+        assert event.available_functions == available_funcs
+
+    @pytest.mark.parametrize("tools_input,expected", [
+        ([{"name": "tool1"}, TokenCalcHandler(TokenProcess())], [{"name": "tool1"}]),
+        ([{"name": "tool1"}, "string_tool", {"name": "tool2"}], [{"name": "tool1"}, {"name": "tool2"}]),
+        ([TokenCalcHandler(TokenProcess()), 123, ["list_tool"]], []),
+        ([{"name": "tool1", "type": "function", "enabled": True}], [{"name": "tool1", "type": "function", "enabled": True}]),
+        ([], []),
+        (None, None),
+    ])
+    def test_tools_sanitization_parameterized(self, tools_input, expected):
+        """Parameterized test for various tools sanitization scenarios"""
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=tools_input,
+            callbacks=None
+        )
+        assert event.tools == expected
+
+    def test_tools_with_invalid_dict_values_filtered(self):
+        """Test that dicts with invalid value types are filtered out"""
+        class CustomObject:
+            pass
+        
+        invalid_tool = {"name": "tool1", "custom_obj": CustomObject()}
+        valid_tool = {"name": "tool2", "type": "function"}
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=[valid_tool, invalid_tool],
+            callbacks=None
+        )
+        
+        assert event.tools == [valid_tool]
+
+    def test_sanitize_tools_performance_large_dataset(self):
+        """Test sanitization performance with large datasets"""
+        token_handler = TokenCalcHandler(TokenProcess())
+        
+        large_tools_list = []
+        for i in range(1000):
+            if i % 3 == 0:
+                large_tools_list.append({"name": f"tool_{i}", "type": "function"})
+            elif i % 3 == 1:
+                large_tools_list.append(token_handler)
+            else:
+                large_tools_list.append(f"string_tool_{i}")
+        
+        event = LLMCallStartedEvent(
+            messages=[{"role": "user", "content": "test message"}],
+            tools=large_tools_list,
+            callbacks=None
+        )
+        
+        expected_count = len([i for i in range(1000) if i % 3 == 0])
+        assert len(event.tools) == expected_count
+        assert all(isinstance(tool, dict) for tool in event.tools)
+
+    def test_sanitization_error_handling(self, caplog):
+        """Test that sanitization errors are handled gracefully"""
+        with caplog.at_level(logging.WARNING):
+            event = LLMCallStartedEvent(
+                messages=[{"role": "user", "content": "test message"}],
+                tools=[{"name": "tool1"}, TokenCalcHandler(TokenProcess())],
+                callbacks=None
+            )
+            
+            assert event.tools == [{"name": "tool1"}]