fix(tools): reject NaN waits and pluralize single-second results

_resolve_duration now rejects NaN with its own message instead of letting
time.sleep raise "Invalid value NaN (not a number)" from a positional
call. Infinity keeps clamping to the cap like any other oversized wait.

Result and description text no longer says "1 seconds". Tests use the
public WaitTool().description as the baseline rather than reaching for
module-private helpers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: joaomdmoura

lib/crewai-tools/src/crewai_tools/tools/wait_tool/wait_tool.py

@@ -1,6 +1,7 @@
 """Tool that pauses execution for a given amount of time."""
 
 import asyncio
+import math
 import time
 from typing import Any
 
@@ -25,13 +26,25 @@
     "Do not use this to pace a conversation, to pretend to work, or when the "
     "information needed is already available. Waiting only lets clock time pass, it "
     "does not advance or check the job.\n"
-    "A single call waits at most {max_seconds} seconds. If more time is needed, "
+    "A single call waits at most {cap}. If more time is needed, "
     "call this tool again."
 )
 
 # Everything before the cap figure; used to tell a generated description from one
 # the caller wrote, so only generated text is kept in sync with ``max_seconds``.
-_GENERATED_DESCRIPTION_PREFIX = _DESCRIPTION_TEMPLATE.split("{max_seconds}")[0]
+_GENERATED_DESCRIPTION_PREFIX = _DESCRIPTION_TEMPLATE.split("{cap}")[0]
+
+
+def _format_seconds(value: float) -> str:
+    """Render a duration with a correctly pluralized unit.
+
+    Args:
+        value: The duration in seconds.
+
+    Returns:
+        The duration and its unit, e.g. ``"1 second"`` or ``"300 seconds"``.
+    """
+    return f"{value:g} second" if value == 1 else f"{value:g} seconds"
 
 
 def _build_description(max_seconds: float) -> str:
@@ -43,7 +56,7 @@ def _build_description(max_seconds: float) -> str:
     Returns:
         The tool description shown to the model.
     """
-    return _DESCRIPTION_TEMPLATE.format(max_seconds=f"{max_seconds:g}")
+    return _DESCRIPTION_TEMPLATE.format(cap=_format_seconds(max_seconds))
 
 
 def _is_generated_description(description: str) -> bool:
@@ -145,8 +158,9 @@ def _resolve_duration(self, seconds: float) -> tuple[float, bool]:
         """Validate and clamp the requested duration to ``max_seconds``.
 
         ``BaseTool.run`` skips ``args_schema`` validation when called with
-        positional arguments, so the non-negative bound is enforced here too
-        rather than left to ``time.sleep`` to reject.
+        positional arguments, so the bounds are enforced here too rather than
+        left to ``time.sleep`` to reject. Infinity is a valid request: it clamps
+        to the cap like any other oversized wait.
 
         Args:
             seconds: The requested wait duration.
@@ -155,8 +169,10 @@ def _resolve_duration(self, seconds: float) -> tuple[float, bool]:
             A tuple of the duration to actually wait and whether it was capped.
 
         Raises:
-            ValueError: If ``seconds`` is negative.
+            ValueError: If ``seconds`` is negative or not a number.
         """
+        if math.isnan(seconds):
+            raise ValueError("seconds must be a number, got NaN.")
         if seconds < 0:
             raise ValueError(f"seconds must be zero or greater, got {seconds:g}.")
         if seconds > self.max_seconds:
@@ -176,10 +192,11 @@ def _format_result(
         Returns:
             A summary of how long was waited and whether the request was capped.
         """
-        parts = [f"Waited {waited:g} seconds."]
+        parts = [f"Waited {_format_seconds(waited)}."]
         if waited < requested:
             parts.append(
-                f"Requested {requested:g} seconds, capped at {self.max_seconds:g} seconds per call - "
+                f"Requested {_format_seconds(requested)}, capped at "
+                f"{_format_seconds(self.max_seconds)} per call - "
                 "call this tool again if more waiting is needed."
             )
         if reason:

lib/crewai-tools/tests/tools/wait_tool_test.py

@@ -1,10 +1,6 @@
 from unittest.mock import AsyncMock, patch
 
 from crewai_tools.tools.wait_tool import WaitTool
-from crewai_tools.tools.wait_tool.wait_tool import (
-    DEFAULT_MAX_SECONDS,
-    _build_description,
-)
 from pydantic import ValidationError
 import pytest
 
@@ -80,6 +76,31 @@ async def test_async_negative_seconds_is_rejected_when_passed_positionally(tool)
     mock_sleep.assert_not_awaited()
 
 
+@patch("crewai_tools.tools.wait_tool.wait_tool.time.sleep")
+def test_nan_seconds_is_rejected_when_passed_positionally(mock_sleep, tool):
+    with pytest.raises(ValueError, match="seconds must be a number"):
+        tool.run(float("nan"))
+
+    mock_sleep.assert_not_called()
+
+
+@patch("crewai_tools.tools.wait_tool.wait_tool.time.sleep")
+def test_infinite_seconds_is_capped_like_any_other_long_wait(mock_sleep, tool):
+    result = tool.run(float("inf"))
+
+    mock_sleep.assert_called_once_with(300)
+    assert "Waited 300 seconds." in result
+
+
+@patch("crewai_tools.tools.wait_tool.wait_tool.time.sleep")
+def test_singular_second_is_not_pluralized(mock_sleep):
+    tool = WaitTool(max_seconds=1)
+
+    assert "Waited 1 second." in tool.run(seconds=1)
+    assert "capped at 1 second per call" in tool.run(seconds=5)
+    assert "at most 1 second." in tool.description
+
+
 def test_invalid_max_seconds_is_rejected():
     with pytest.raises(ValidationError):
         WaitTool(max_seconds=0)
@@ -114,7 +135,7 @@ async def test_async_wait_caps_long_waits(tool):
     ],
 )
 def test_advertised_cap_matches_enforced_cap(build):
-    tool = build(_build_description(DEFAULT_MAX_SECONDS))
+    tool = build(WaitTool().description)
 
     assert tool.max_seconds == 10
     assert "at most 10 seconds" in tool.description
@@ -139,7 +160,7 @@ def test_waits_are_never_cached():
     # turning a poll-wait-check loop into a busy loop.
     tool = WaitTool()
 
-    assert tool.cache_function("{}", "Waited 1 seconds.") is False
+    assert tool.cache_function("{}", "Waited 1 second.") is False
     assert WaitTool.model_validate(tool.model_dump()).cache_function() is False