[BUG] @tool emits PydanticJsonSchemaWarning for Field(default_factory=list)

[tealgreen0503]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.30.0

Python Version

3.11.x

Operating System

macOS 15.7

Installation Method

pip

Steps to Reproduce

from pydantic import Field
from strands import Agent, tool

@tool
def example(
    items: list[str] = Field(default_factory=list, description="items"),
) -> int:
    """Example tool."""
    return len(items)

Agent(tools=[example])
# PydanticJsonSchemaWarning: Default value annotation=NoneType required=False default_factory=list description='items' is not JSON serializable; excluding default from JSON schema [non-serializable-default]

Expected Behavior

No warning should be emitted. default_factory=list should be handled correctly when Strands builds the tool input schema.

Actual Behavior

Strands emits a Pydantic warning while generating the tool schema:

PydanticJsonSchemaWarning: Default value ... default_factory=list ... is not JSON serializable; excluding default from JSON schema

This looks like the decorator rebuilds the field as Field(default=<FieldInfo>), so Pydantic sees a non-serializable default.

Additional Context

I could not find an issue for this exact warning, but it looks related to the custom tool-validation/schema path discussed in #1246 and #917. It also seems similar in spirit to #337, but this case is about function-tool parameters using Field(default_factory=...).

Possible Solution

If a parameter default is already a Pydantic FieldInfo, preserve it instead of wrapping it again in Field(default=param_default, ...).

Related Issues

No response

[shivamnegi1705]

Hi @tealgreen0503 , can you assign this bug to me ? I would like to work on this.

[shivamnegi1705]

Based on my investigation of the code path, this is my understanding of the root cause and a possible fix. Please feel free to point out if I have misinterpreted any part.

Root Cause

The bug originates in FunctionToolMetadata._extract_annotated_metadata located in src/strands/tools/decorator.py.

1. When a user defines a tool like this:

@tool
def example(items: list[str] = Field(default_factory=list, description="items")) -> int:

Python evaluates Field(default_factory=list, description="items") at function definition time and stores the resulting FieldInfo object as param.default in the function signature. This means the default value is not [], but a Pydantic metadata object.

2. Inside _create_input_model, the default is extracted using:

default = ... if param.default is inspect.Parameter.empty else param.default

Since the default is not empty, default becomes the FieldInfo object itself. This value is then passed as param_default to _extract_annotated_metadata.

3. Because the annotation is a plain list[str] (not Annotated[...]), the method skips the Annotated branch and reaches:

final_field = Field(default=param_default, description=final_description)

4. This effectively creates:

Field(default=<FieldInfo object>, ...)

which wraps a FieldInfo inside another Field as its default value.

When Pydantic attempts to generate the JSON schema, it tries to serialize the default value. Since a FieldInfo object is not JSON-serializable, Pydantic emits a PydanticJsonSchemaWarning and drops the default from the schema.

Fix

Before creating a new Field, check whether param_default is already a FieldInfo. If it is, rebuild a clean Field using its attributes (default, default_factory, and description) instead of wrapping it again.

if isinstance(param_default, FieldInfo):
    field_kwargs: dict[str, Any] = {}

    if param_default.default_factory is not None:
        field_kwargs["default_factory"] = param_default.default_factory
    elif param_default.default is not PydanticUndefined:
        field_kwargs["default"] = param_default.default

    field_kwargs["description"] = param_default.description or final_description

    return actual_type, Field(**field_kwargs)

We intentionally rebuild a fresh Field rather than reusing the original FieldInfo. In Pydantic v2, the Core Schema is frozen after construction, meaning mutating attributes (such as .description) on an existing FieldInfo does not reliably propagate to the generated JSON schema.

This fix ensures that:

• default_factory is preserved correctly.
• the user's description is respected (falling back to the docstring when absent).
• the generated schema is clean and no PydanticJsonSchemaWarning is emitted.

---

Note:
This would be a targeted fix. The broader architectural proposal in issue #1246 (replacing custom validation with validate_call) would eliminate this class of bugs entirely by removing _extract_annotated_metadata altogether.

[tealgreen0503]

@shivamnegi1705

Hi @tealgreen0503 , can you assign this bug to me ? I would like to work on this.

of course!

[frankgoldfish]

Hi! I submitted PR #1923 addressing this. The fix strips non-JSON-serializable default values (like FieldInfo objects from default_factory) in _clean_pydantic_schema() before schema generation. Added a regression test that asserts no UserWarning is raised.

Note: I submitted without commenting first — apologies for skipping that step. Happy to iterate if the approach needs adjustment.