feat(tools): add support for string descriptions in Annotated

Author: Ratish1

src/strands/tools/decorator.py

@@ -44,7 +44,6 @@ def my_tool(param1: str, param2: int = 42) -> dict:
 import functools
 import inspect
 import logging
-from copy import copy
 from typing import (
     Annotated,
     Any,
@@ -65,7 +64,6 @@ def my_tool(param1: str, param2: int = 42) -> dict:
 import docstring_parser
 from pydantic import BaseModel, Field, create_model
 from pydantic.fields import FieldInfo
-from pydantic_core import PydanticUndefined
 from typing_extensions import override
 
 from ..interrupt import InterruptException
@@ -119,47 +117,57 @@ def __init__(self, func: Callable[..., Any], context_param: str | None = None) -
     def _extract_annotated_metadata(
         self, annotation: Any, param_name: str, param_default: Any
     ) -> tuple[Any, FieldInfo]:
-        """Extract type and create FieldInfo from Annotated type hint.
+        """Extracts type and a simple string description from an Annotated type hint.
 
         Returns:
-            (actual_type, field_info) where field_info is always a FieldInfo instance
+            A tuple of (actual_type, field_info), where field_info is a new, simple
+            Pydantic FieldInfo instance created from the extracted metadata.
         """
         actual_type = annotation
-        field_info: FieldInfo | None = None
         description: str | None = None
 
         if get_origin(annotation) is Annotated:
             args = get_args(annotation)
             actual_type = args[0]
+
+            # Look through metadata for a string description or a FieldInfo object.
             for meta in args[1:]:
-                if isinstance(meta, FieldInfo):
-                    field_info = meta
-                elif isinstance(meta, str):
+                if isinstance(meta, str):
                     description = meta
+                elif isinstance(meta, FieldInfo):
+                    # --- Future Contributor Note ---
+                    # We are explicitly blocking the use of `pydantic.Field` within `Annotated`
+                    # because of the complexities of Pydantic v2's immutable Core Schema.
+                    #
+                    # Once a Pydantic model's schema is built, its `FieldInfo` objects are
+                    # effectively frozen. Attempts to mutate a `FieldInfo` object after
+                    # creation (e.g., by copying it and setting `.description` or `.default`)
+                    # are unreliable because the underlying Core Schema does not see these changes.
+                    #
+                    # The correct way to support this would be to reliably extract all
+                    # constraints (ge, le, pattern, etc.) from the original FieldInfo and
+                    # rebuild a new one from scratch. However, these constraints are not
+                    # stored as public attributes, making them difficult to inspect reliably.
+                    #
+                    # Deferring this complexity until there is clear demand and a robust
+                    # pattern for inspecting FieldInfo constraints is established.
+                    raise NotImplementedError(
+                        "Using pydantic.Field within Annotated is not yet supported for tool decorators. "
+                        "Please use a simple string for the description, or define constraints in the function's "
+                        "docstring."
+                    )
 
-        # Final description — always a string, never None
-        final_description = (
-            description
-            if description is not None
-            else (
-                field_info.description
-                if field_info and field_info.description is not None
-                else self.param_descriptions.get(param_name) or f"Parameter {param_name}"
-            )
-        )
-
-        # Build final FieldInfo
-        if field_info:
-            final_field = copy(field_info)
-            final_field.description = final_description
-
-            # ONLY override default if Field has no default AND signature has one.
-            # Pydantic uses `PydanticUndefined` to signify no default was provided,
-            # which is distinct from an explicit default of `None`.
-            if field_info.default is PydanticUndefined and param_default is not ...:
-                final_field.default = param_default
-        else:
-            final_field = Field(default=param_default, description=final_description)
+        # Determine the final description with a clear priority order.
+        # Priority: 1. Annotated string -> 2. Docstring -> 3. Fallback
+        final_description = description
+        if final_description is None:
+            final_description = self.param_descriptions.get(param_name)
+        if final_description is None:
+            final_description = f"Parameter {param_name}"
+
+        # Create a new, simple FieldInfo object from scratch.
+        # This avoids all the immutability and mutation issues we encountered previously.
+        final_field = Field(default=param_default, description=final_description)
 
         return actual_type, final_field
 

tests/strands/tools/test_decorator.py

@@ -1484,30 +1484,16 @@ def annotated_tool(
 
 
 def test_tool_decorator_annotated_pydantic_field_constraints():
-    """Test tool decorator with Pydantic Field in Annotated."""
+    """Test that using pydantic.Field in Annotated raises a NotImplementedError."""
+    with pytest.raises(NotImplementedError, match="Using pydantic.Field within Annotated is not yet supported"):
 
-    @strands.tool
-    def field_annotated_tool(
-        email: Annotated[str, Field(description="User's email address", pattern=r"^[\w\.-]+@[\w\.-]+\\.\w+$")],
-        score: Annotated[int, Field(description="Score between 0-100", ge=0, le=100)] = 50,
-    ) -> str:
-        """Tool with Pydantic Field annotations."""
-        return f"{email}: {score}"
-
-    spec = field_annotated_tool.tool_spec
-    schema = spec["inputSchema"]["json"]
-
-    # Check descriptions from Field
-    assert schema["properties"]["email"]["description"] == "User's email address"
-    assert schema["properties"]["score"]["description"] == "Score between 0-100"
-
-    # Check that constraints are preserved
-    assert schema["properties"]["score"]["minimum"] == 0
-    assert schema["properties"]["score"]["maximum"] == 100
-
-    # Check required fields
-    assert "email" in schema["required"]
-    assert "score" not in schema["required"]  # Has default
+        @strands.tool
+        def field_annotated_tool(
+            email: Annotated[str, Field(description="User's email address", pattern=r"^[\w\.-]+@[\w\.-]+\\.w+$")],
+            score: Annotated[int, Field(description="Score between 0-100", ge=0, le=100)] = 50,
+        ) -> str:
+            """Tool with Pydantic Field annotations."""
+            return f"{email}: {score}"
 
 
 def test_tool_decorator_annotated_overrides_docstring():
@@ -1574,31 +1560,23 @@ def complex_annotated_tool(
 
 
 def test_tool_decorator_annotated_mixed_styles():
-    """Test tool with mixed annotation styles."""
-
-    @strands.tool
-    def mixed_tool(
-        plain: str,
-        annotated_str: Annotated[str, "String description"],
-        annotated_field: Annotated[int, Field(description="Field description", ge=0)],
-        docstring_only: int,
-    ) -> str:
-        """Tool with mixed parameter styles.
-
-        Args:
-            plain: Plain parameter description
-            docstring_only: Docstring description for this param
-        """
-        return "mixed"
+    """Test that using pydantic.Field in a mixed-style annotation raises NotImplementedError."""
+    with pytest.raises(NotImplementedError, match="Using pydantic.Field within Annotated is not yet supported"):
 
-    spec = mixed_tool.tool_spec
-    schema = spec["inputSchema"]["json"]
+        @strands.tool
+        def mixed_tool(
+            plain: str,
+            annotated_str: Annotated[str, "String description"],
+            annotated_field: Annotated[int, Field(description="Field description", ge=0)],
+            docstring_only: int,
+        ) -> str:
+            """Tool with mixed parameter styles.
 
-    # Check each style works correctly
-    assert schema["properties"]["plain"]["description"] == "Plain parameter description"
-    assert schema["properties"]["annotated_str"]["description"] == "String description"
-    assert schema["properties"]["annotated_field"]["description"] == "Field description"
-    assert schema["properties"]["docstring_only"]["description"] == "Docstring description for this param"
+            Args:
+                plain: Plain parameter description
+                docstring_only: Docstring description for this param
+            """
+            return "mixed"
 
 
 @pytest.mark.asyncio
@@ -1624,24 +1602,19 @@ def execution_test(name: Annotated[str, "User name"], count: Annotated[int, "Num
 
 
 def test_tool_decorator_annotated_no_description_fallback():
-    """Test that Annotated without description falls back to docstring."""
+    """Test that Annotated with a Field raises NotImplementedError."""
+    with pytest.raises(NotImplementedError, match="Using pydantic.Field within Annotated is not yet supported"):
 
-    @strands.tool
-    def no_desc_annotated(
-        param: Annotated[str, Field()],  # Field without description
-    ) -> str:
-        """Tool with Annotated but no description.
-
-        Args:
-            param: Docstring description
-        """
-        return param
-
-    spec = no_desc_annotated.tool_spec
-    schema = spec["inputSchema"]["json"]
+        @strands.tool
+        def no_desc_annotated(
+            param: Annotated[str, Field()],  # Field without description
+        ) -> str:
+            """Tool with Annotated but no description.
 
-    # Should fall back to docstring
-    assert schema["properties"]["param"]["description"] == "Docstring description"
+            Args:
+                param: Docstring description
+            """
+            return param
 
 
 def test_tool_decorator_annotated_empty_string_description():
@@ -1683,16 +1656,9 @@ def validation_tool(age: Annotated[int, "User age"]) -> str:
 
 
 def test_tool_decorator_annotated_field_with_inner_default():
-    """Test that a default value in an Annotated Field is respected."""
-
-    @strands.tool
-    def inner_default_tool(name: str, level: Annotated[int, Field(description="A level value", default=10)]) -> str:
-        return f"{name} is at level {level}"
-
-    spec = inner_default_tool.tool_spec
-    schema = spec["inputSchema"]["json"]
+    """Test that a default value in an Annotated Field raises NotImplementedError."""
+    with pytest.raises(NotImplementedError, match="Using pydantic.Field within Annotated is not yet supported"):
 
-    # 'level' should not be required because its Field has a default
-    assert "name" in schema["required"]
-    assert "level" not in schema["required"]
-    assert schema["properties"]["level"]["default"] == 10
+        @strands.tool
+        def inner_default_tool(name: str, level: Annotated[int, Field(description="A level value", default=10)]) -> str:
+            return f"{name} is at level {level}"