fix(tool/decorator): validate ToolContext parameter name and raise clear error

[Ratish1]

Description

When a tool function uses ToolContext but the parameter name doesn't match the decorator's `context` configuration (or `context=True` was omitted), Pydantic raised an opaque error during schema generation. This PR proactively validates ToolContext usage at decoration time and raises a clear TypeError explaining the mismatch or missing decorator flag.

Key Changes

• Add validation in FunctionToolMetadata to detect parameters annotated with ToolContext and:
  • require @tool(context=True) (or context="name") when ToolContext is present, and
  • require the parameter name to match the configured context name.
• Add three unit tests to tests/strands/tools/test_decorator.py verifying:
  • mismatched parameter name raises a clear TypeError,
  • ToolContext used without context=True raises a clear TypeError,
  • mismatched custom context name raises a clear TypeError.

Related Issues

Fixes #1020

Documentation PR

N/A

Type of Change

Bug fix

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare
• I ran pre-commit hooks, formatting and linting
• I ran the new unit tests:
• tests/strands/tools/test_decorator.py::test_tool_with_mismatched_tool_context_param_name_raises_error → passed
• tests/strands/tools/test_decorator.py::test_tool_with_tool_context_but_no_context_flag_raises_error → passed
• tests/strands/tools/test_decorator.py::test_tool_with_tool_context_named_custom_context_raises_error_if_mismatched → passed

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[pgrayy]

See comment under "Files changed"

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!