fix: preserve Annotated metadata in function tool declarations and arg conversion

[MarlzRana]

Link to Issue or Description of Change

2. Or, if no issue exists, describe the change:

Problem:

When the JSON_SCHEMA_FOR_FUNC_DECL feature is enabled, typing.Annotated metadata was silently dropped in two places:

1. Declaration builder. _function_tool_declarations._get_function_fields called get_type_hints() without include_extras=True, so Annotated[T, Field(description=..., ge=1)] was unwrapped to a bare T before Pydantic's create_model saw it. Every description and constraint an author attached via Annotated was missing from the schema shown to the model. The legacy builder never had this problem, so this was a regression between the two paths.

2. Argument conversion. FunctionTool._preprocess_args resolves parameter types with get_type_hints(), which strips Annotated for free. But when get_type_hints() cannot resolve a signature (an unresolvable forward reference anywhere in it — e.g. a TYPE_CHECKING-only import or a recursive type alias), it raises and the code falls back to the raw param.annotation, which is still Annotated-wrapped. None of the conversion branches recognised the wrapper, so JSON dicts from the model reached the function body unconverted (later AttributeError).

Solution:

• Pass include_extras=True to get_type_hints() in the JSON-schema declaration builder (parameter and forward-ref return paths), so Annotated metadata reaches the generated schema — matching the legacy builder.
• Unwrap Annotated in _preprocess_args, both at the top level and per union member (Optional[Annotated[T, ...]] hides the wrapper inside the union), so dict-to-model conversion works on the fallback path too.

Known limitations left out of scope: list[Annotated[Model, ...]] on the fallback path (degrades gracefully — passes the dict through, no crash), and a top-level Field(alias=...) now renaming a schema property. Both are documented for follow-up.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Added 16 tests across three existing files:

• test_function_tool_declarations.py — Annotated metadata (descriptions, constraints, defaults, optional models, nested lists, return type) reaches the JSON schema.
• test_build_function_declaration.py — parity pair asserting the legacy and JSON-schema builders both preserve Annotated metadata.
• test_function_tool_pydantic.py — _preprocess_args conversion on both the resolved and the get_type_hints-fallback paths, plus an end-to-end run_async case.

Each fix was verified by reverting it and confirming the corresponding tests fail (the e2e test fails with AttributeError: 'dict' object has no attribute 'name', the real symptom).

$ pytest tests/unittests/tools/test_function_tool_declarations.py \
         tests/unittests/tools/test_build_function_declaration.py \
         tests/unittests/tools/test_function_tool_pydantic.py \
         tests/unittests/tools/test_function_tool.py \
         tests/unittests/tools/test_function_tool_with_import_annotations.py
162 passed, 2 warnings

Manual End-to-End (E2E) Tests:

Not applicable — the behaviour is fully exercised by the unit tests, including an end-to-end run_async invocation that asserts the wrapped function receives a real Pydantic model instance rather than a dict.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[MarlzRana]

I will re-open this later after a bit more polish.