[surlymochan]

Human Overview

Description

A @tool parameter named agent is silently excluded from the generated inputSchema, and at call time it receives the invoking Agent instance from invocation_state, bypassing validation entirely. When the parameter carries an ordinary annotation such as Literal["reviewer", "explorer"], both halves fail invisibly: the model never sees the parameter, and the tool body receives an Agent object where its annotation promises something else.

This makes the collision loud at definition time, following option (1) + (3) from #3499. FunctionToolMetadata now checks the agent parameter when a tool is defined: if it is annotated with a type that cannot hold an Agent (unwrapping Annotated and unions; Agent subclasses pass), it emits a UserWarning naming the parameter and the remedy — rename it, or annotate it as Agent. Unannotated and Any-annotated parameters keep the current behavior, as does a context parameter that happens to be named agent. The @tool docstring now documents the reserved parameter names (self, cls, agent).

A warning rather than an error: injection into an annotated agent parameter is existing, tested behavior (test_stream_with_agent injects into agent: dict), so rejecting it outright would break working tools. The warning follows the codebase convention for developer-facing usage notices (warnings.warn with stacklevel, as in models/_validation.py).

Related Issues

Fixes #3499

Documentation PR

None needed. The reserved parameter names are documented in the @tool docstring itself.

Type of Change

Bug fix

Testing

• Issue reproduction script (the exact delegate tool from Tool parameter named agent is silently dropped from inputSchema (reserved special parameter, no warning) #3499): now emits the UserWarning at definition time; agent: Agent and untyped agent tools are still created with agent excluded from the schema.

• tests/strands/tools/test_decorator.py — 79 passed, including 4 new tests (warning on a Literal-annotated agent, schema exclusion for Agent and Agent | None annotations, exemption for a context parameter named agent). The 10 remaining failures in that file are pre-existing sandbox issues (botocore reaching the EC2 metadata endpoint while constructing a default Bedrock-backed Agent); the same tests fail identically on an unmodified checkout in this environment.

• ruff format --check and ruff check on both changed files — clean (standalone ruff).

• mypy on src/strands/tools/decorator.py — no new errors (standalone run with imports skipped reports the same 5 pre-existing errors as an unmodified checkout; the full static-analysis env could not be built in this sandbox).

• I ran hatch run prepare (could not build the hatch-static-analysis env in this sandbox; the test, ruff, and mypy checks listed above were run instead)

Additional Details

Extended context (optional)

Design discussion on #3499 converged on flagging the collision when the tool is defined rather than at call time. Two of the proposals suggested raising ValueError; this PR warns instead, because tests/strands/tools/test_decorator.py::test_stream_with_agent codifies injection into an agent: dict parameter as supported behavior, and a hard error would break that contract for every existing tool that relies on it. If maintainers prefer the stricter behavior, the check in FunctionToolMetadata._validate_agent_parameter is the single place to change.

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• 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.