Lorenze/max retry defaults tools (#3362)

* feat: enhance BaseTool and CrewStructuredTool with usage tracking

This commit introduces a mechanism to track the usage count of tools within the CrewAI framework. The `BaseTool` class now includes a `_increment_usage_count` method that updates the current usage count, which is also reflected in the associated `CrewStructuredTool`. Additionally, a new test has been added to ensure that the maximum usage count is respected when invoking tools, enhancing the overall reliability and functionality of the tool system.

* feat: add max usage count feature to tools documentation

This commit introduces a new section in the tools overview documentation that explains the maximum usage count feature for tools within the CrewAI framework. Users can now set a limit on how many times a tool can be used, enhancing control over tool usage. An example of implementing the `FileReadTool` with a maximum usage count is also provided, improving the clarity and usability of the documentation.

* undo field string

tests/tools/test_base_tool.py

@@ -1,9 +1,12 @@
 import asyncio
-import inspect
-import unittest
-from typing import Any, Callable, Dict, List
+from typing import Callable
 from unittest.mock import patch
 
+import pytest
+
+from crewai.agent import Agent
+from crewai.crew import Crew
+from crewai.task import Task
 from crewai.tools import BaseTool, tool
 
 
@@ -111,25 +114,26 @@ def test_result_as_answer_in_tool_decorator():
     def my_tool_with_result_as_answer(question: str) -> str:
         """This tool will return its result as the final answer."""
         return question
-    
+
     assert my_tool_with_result_as_answer.result_as_answer is True
-    
+
     converted_tool = my_tool_with_result_as_answer.to_structured_tool()
     assert converted_tool.result_as_answer is True
-    
+
     @tool("Tool with default result_as_answer")
     def my_tool_with_default(question: str) -> str:
         """This tool uses the default result_as_answer value."""
         return question
-    
+
     assert my_tool_with_default.result_as_answer is False
-    
+
     converted_tool = my_tool_with_default.to_structured_tool()
     assert converted_tool.result_as_answer is False
 
 
 class SyncTool(BaseTool):
     """Test implementation with a synchronous _run method"""
+
     name: str = "sync_tool"
     description: str = "A synchronous tool for testing"
 
@@ -140,6 +144,7 @@ class SyncTool(BaseTool):
 
 class AsyncTool(BaseTool):
     """Test implementation with an asynchronous _run method"""
+
     name: str = "async_tool"
     description: str = "An asynchronous tool for testing"
 
@@ -174,7 +179,7 @@ def test_run_calls_asyncio_run_for_async_tools():
     """Test that asyncio.run is called when using async tools."""
     async_tool = AsyncTool()
 
-    with patch('asyncio.run') as mock_run:
+    with patch("asyncio.run") as mock_run:
         mock_run.return_value = "Processed test asynchronously"
         async_result = async_tool.run(input_text="test")
 
@@ -186,9 +191,43 @@ def test_run_does_not_call_asyncio_run_for_sync_tools():
     """Test that asyncio.run is NOT called when using sync tools."""
     sync_tool = SyncTool()
 
-    with patch('asyncio.run') as mock_run:
+    with patch("asyncio.run") as mock_run:
         sync_result = sync_tool.run(input_text="test")
 
         mock_run.assert_not_called()
         assert sync_result == "Processed test synchronously"
 
+
+@pytest.mark.vcr(filter_headers=["authorization"])
+def test_max_usage_count_is_respected():
+    class IteratingTool(BaseTool):
+        name: str = "iterating_tool"
+        description: str = "A tool that iterates a given number of times"
+
+        def _run(self, input_text: str):
+            return f"Iteration {input_text}"
+
+    tool = IteratingTool(max_usage_count=5)
+
+    agent = Agent(
+        role="Iterating Agent",
+        goal="Call the iterating tool 5 times",
+        backstory="You are an agent that iterates a given number of times",
+        tools=[tool],
+    )
+
+    task = Task(
+        description="Call the iterating tool 5 times",
+        expected_output="A list of the iterations",
+        agent=agent,
+    )
+
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=True,
+    )
+
+    crew.kickoff()
+    assert tool.max_usage_count == 5
+    assert tool.current_usage_count == 5