[BUG] Opaque Pydantic error when ToolContext is provided with mismatched parameter name

[Lilja-at-funnel]

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.11.0

Python Version

3.13.3

Operating System

macOs 15.6.1

Installation Method

pip

Steps to Reproduce

# test.py
from strands import Agent, tool, ToolContext

@tool(context=True)
def test(context: ToolContext) -> dict:
    return {"success": True, "message": "The tool is working!"}

$ uv run test.py
Traceback (most recent call last):
  File "/Users/lilja/code/connector-agents/connector-agents/test.py", line 3, in <module>
    @tool(context=True)
     ~~~~^^^^^^^^^^^^^^
  File "/Users/lilja/code/connector-agents/connector-agents/.venv/lib/python3.13/site-packages/strands/tools/decorator.py", line 636, in decorator
    tool_spec = tool_meta.extract_metadata()
  File "/Users/lilja/code/connector-agents/connector-agents/.venv/lib/python3.13/site-packages/strands/tools/decorator.py", line 175, in extract_metadata
    input_schema = self.input_model.model_json_schema()
  File "/Users/lilja/code/connector-agents/connector-agents/.venv/lib/python3.13/site-packages/pydantic/main.py", line 555, in model_json_schema
    return model_json_schema(
        cls, by_alias=by_alias, ref_template=ref_template, schema_generator=schema_generator, mode=mode
    )
  File "/Users/lilja/code/connector-agents/connector-agents/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 2407, in model_json_schema
    cls.__pydantic_core_schema__.rebuild()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/lilja/code/connector-agents/connector-agents/.venv/lib/python3.13/site-packages/pydantic/_internal/_mock_val_ser.py", line 67, in rebuild
    raise PydanticUserError(self._error_message, code=self._code)
pydantic.errors.PydanticUserError: `TestTool` is not fully defined; you should define `Agent`, then call `TestTool.model_rebuild()`.

For further information visit https://errors.pydantic.dev/2.11/u/class-not-fully-defined

Expected Behavior

Actual Behavior

Additional Context

No response

Possible Solution

No response

Related Issues

No response

[Lilja-at-funnel]

Hmm, it worked by renaming the parameter to tool_context.

[dbschmigelski]

Hi thanks for raising the documentation PR. I chatted with @zastrowm about this. We think in addition to the docs PR, the framework can help by being proactive and raising an exception before the user sees the, somewhat opaque,

pydantic.errors.PydanticUserError: TestTool is not fully defined; you should define Agent, then call TestTool.model_rebuild().

The fix here would be, when adding a tool, to verify that there is no mismatch.

[Ratish1]

Hi, I want to contribute to this or are you working on it already, @Lilja-at-funnel .