docs: Add comprehensive analysis of issue #3281 and PR #3280 review

This commit contains detailed analysis materials for investigating and
reviewing the nullable fields bug with Google GenAI bump.

Analysis Materials:
- issue_3281_analysis.md: Root cause analysis and detailed bug flow
- pr_3280_review.md: Comprehensive review of the proposed fix

Test Scripts (for reproduction and validation):
- test_nullable_issue.py: Basic reproduction of the Pydantic schema issue
- test_sanitize_issue.py: Demonstrates the problematic transformation
- test_exact_adk_flow.py: Traces the complete ADK processing flow
- test_anyof_unwrap.py: Shows google-genai can unwrap correctly
- test_unwrap_with_description.py: Tests unwrapping with metadata
- test_gemini_api_error.py: Analyzes the schema structure problem
- test_fix_proposal.py: Initial fix approach (tracking anyOf context)
- test_pr_3280_fix.py: Validates the PR #3280 approach
- test_pr_edge_cases.py: Comprehensive edge case testing

Key Findings:
- Root cause: _sanitize_schema_type transforms {"type": "null"} to
  {"type": ["object", "null"]} which breaks google-genai unwrapping
- PR #3280 correctly fixes this by removing _sanitize_schema_type
  entirely and deferring to google-genai>=1.45.0
- All edge cases are properly handled by the new approach
- The fix is minimal, clean, and improves type handling overall

Recommendation: APPROVE PR #3280

Related: #3281, PR #3280

Author: Jacksunwei

issue_3281_analysis.md

@@ -0,0 +1,105 @@
+# Issue #3281: Nullable Fields Broken with Google GenAI Bump
+
+## Root Cause Analysis
+
+### The Problem
+
+When defining MCP tools with optional parameters using Pydantic's `int | None` or `str | None` type hints (OpenAPI 3.1 style), the Gemini API returns a 400 error:
+
+```
+Unable to submit request because `create_payee` functionDeclaration `parameters.person.age` schema specified other fields alongside any_of. When using any_of, it must be the only field set.
+```
+
+### The Bug
+
+The issue is in **`_sanitize_schema_type` function** in [`src/google/adk/tools/_gemini_schema_util.py:96-97`](src/google/adk/tools/_gemini_schema_util.py#L96-L97):
+
+```python
+elif schema.get("type") == "null":
+    schema["type"] = ["object", "null"]
+```
+
+This transformation breaks the `anyOf` unwrapping logic in `google-genai`'s `Schema.from_json_schema`.
+
+### Detailed Flow
+
+1. **Pydantic generates** (OpenAPI 3.1 style):
+   ```json
+   {
+     "anyOf": [
+       {"type": "integer", "minimum": 0},
+       {"type": "null"}
+     ],
+     "description": "Person's age"
+   }
+   ```
+
+2. **ADK's `_sanitize_schema_formats_for_gemini` recursively processes** the `anyOf` elements
+   - First element `{"type": "integer", "minimum": 0}` → stays as-is
+   - Second element `{"type": "null"}` → **transforms to `{"type": ["object", "null"]}`** (LINE 97)
+
+3. **Result after sanitization**:
+   ```json
+   {
+     "any_of": [
+       {"type": "integer", "minimum": 0},
+       {"type": ["object", "null"]}  ← PROBLEM!
+     ],
+     "description": "Person's age"
+   }
+   ```
+
+4. **google-genai's unwrapping logic** (in `Schema.from_json_schema`, lines 2232-2250):
+   - Expects: `{"type": "null"}` or `{"nullable": True}`
+   - Gets: `{"type": ["object", "null"]}`
+   - **Fails to unwrap** because it doesn't match the expected pattern
+
+5. **Result**: Schema sent to Vertex AI has:
+   ```
+   any_of: [Schema(type=INTEGER), Schema(type=OBJECT, nullable=True)]
+   description: "Person's age"
+   type: OBJECT
+   ```
+   This violates Vertex AI's constraint: "when using any_of, it must be the only field set"
+
+### Why This Line Exists
+
+The `_sanitize_schema_type` function line 96-97 was likely added to handle standalone `{"type": "null"}` schemas, converting them to something Gemini can understand. However, it should **NOT** be applied to schemas that are part of an `anyOf` array used for representing nullable types.
+
+### The Fix
+
+The `_sanitize_schema_type` function should NOT transform `{"type": "null"}` when it's inside an `anyOf` array that's being used to represent nullable types. The google-genai library is designed to handle this unwrapping automatically.
+
+**Recommended Solution**: Modify `_sanitize_schema_formats_for_gemini` to track when it's processing elements inside `any_of`, and skip the `{"type": "null"}` → `{"type": ["object", "null"]}` transformation in that context.
+
+**Code Changes Required**:
+1. Add an `in_any_of` parameter to `_sanitize_schema_formats_for_gemini` and `_sanitize_schema_type`
+2. Set `in_any_of=True` when recursively processing elements of `any_of` lists
+3. Skip the line 96-97 transformation when `in_any_of=True`
+4. Update the test `test_sanitize_schema_formats_for_gemini_nullable` to expect `{"type": "null"}` instead of `{"type": ["object", "null"]}`
+5. Add an end-to-end test using `_to_gemini_schema` to verify the anyOf unwrapping works correctly
+
+**Alternative Solutions** (not recommended):
+- **Option 2**: Remove all anyOf pre-processing and let google-genai handle everything (may break other cases)
+- **Option 3**: Remove the line 96-97 transformation entirely (would break standalone `{"type": "null"}` schemas)
+
+### Impact
+
+- Affects all tools with optional parameters using Python 3.10+ union syntax (`Type | None`)
+- Affects MCP tools particularly, as they often use optional parameters
+- Regression introduced with google-genai v1.45.0+ which added stricter anyOf validation
+
+### Workarounds
+
+Until fixed, users can:
+1. Avoid using optional parameters (not practical)
+2. Downgrade google-genai to v1.44.0 (may have other implications)
+3. Use OpenAPI 3.0 style with `required` field instead of nullable (breaks Pydantic patterns)
+
+## Test Cases
+
+See:
+- `test_nullable_issue.py` - Demonstrates the original Pydantic schema
+- `test_sanitize_issue.py` - Shows the problematic transformation
+- `test_exact_adk_flow.py` - Confirms the unwrapping failure
+- `test_anyof_unwrap.py` - Shows google-genai can unwrap when given correct input

pr_3280_review.md

@@ -0,0 +1,99 @@
+# PR #3280 Review: Fix for Nullable Types with GenAI Bump
+
+## Summary
+**Status: ✅ CORRECT FIX**
+
+PR #3280 correctly fixes issue #3281 by removing the problematic `_sanitize_schema_type` function and deferring to google-genai>=1.45.0 for proper nullable type handling.
+
+## Root Cause (Confirmed)
+The bug was in `_sanitize_schema_type` function at lines 96-97:
+```python
+elif schema.get("type") == "null":
+    schema["type"] = ["object", "null"]
+```
+
+This transformation broke google-genai's anyOf unwrapping logic, causing Vertex AI to reject schemas with the error:
+> "schema specified other fields alongside any_of. When using any_of, it must be the only field set"
+
+## The Fix
+
+### Code Changes ✅
+1. **Removes entire `_sanitize_schema_type` function** (lines 77-99)
+   - This was causing the conflicting type transformations
+   - google-genai>=1.45.0 handles all these cases properly
+
+2. **Simplifies `_sanitize_schema_formats_for_gemini`**
+   - Removes call to `_sanitize_schema_type`
+   - Adds simple empty schema handling: `if not snake_case_schema: snake_case_schema["type"] = "object"`
+   - Passes schemas to google-genai without mangling the type field
+
+3. **Bumps google-genai requirement** to `>=1.45.0`
+   - Version 1.45.0 has improved nullable type handling
+   - Includes the anyOf unwrapping logic that ADK was breaking
+
+### Test Changes ✅
+
+1. **Removes `test_sanitize_schema_formats_for_gemini_nullable`**
+   - This test was asserting INCORRECT behavior
+   - Expected `{"type": ["object", "null"]}` which breaks unwrapping
+   - Correct to remove it
+
+2. **Adds `test_to_gemini_schema_any_of_nullable`**
+   - Tests the end-to-end anyOf unwrapping
+   - Verifies `{"anyOf": [{"type": "string"}, {"type": "null"}]}` → `{type: STRING, nullable: True}`
+   - This is the critical test for the fix ✅
+
+3. **Updates `test_to_gemini_schema_array_string_types`**
+   - Changes `"object_nullable"` to `"nullable_object"` with proper schema
+   - Adds `"only_null"` test case for standalone null type
+   - Updates `"multi_types_nullable"` expectation to use anyOf (more correct)
+   - All changes reflect the new, more correct behavior ✅
+
+## Edge Case Analysis ✅
+
+All edge cases previously handled by `_sanitize_schema_type` are now handled by google-genai>=1.45.0:
+
+| Case | Old Behavior | New Behavior | Status |
+|------|--------------|--------------|--------|
+| Empty schema `{}` | Adds `type: object` | Still adds `type: object` | ✅ Same |
+| Standalone `{"type": "null"}` | → `["object", "null"]` | → `nullable: True` | ✅ Better |
+| `["string", "null"]` | Keeps as-is | → `{type: STRING, nullable: True}` | ✅ Better |
+| `["null", "integer"]` | → `["integer", "null"]` | → `{type: INTEGER, nullable: True}` | ✅ Better |
+| `["string", "integer", "null"]` | → `["string", "null"]` (loses integer!) | → `{any_of: [STRING, INTEGER], nullable: True}` | ✅ Much Better |
+| anyOf with null | → `{type: ["object", "null"]}` (broken!) | → unwraps correctly | ✅ **FIXES THE BUG** |
+
+## Concerns Addressed
+
+### ❓ Why was `_sanitize_schema_type` added originally?
+- Added in commit b1a74d09 to "tolerate more cases"
+- Was needed when google-genai had less sophisticated type handling
+- With google-genai>=1.45.0, it's now redundant and harmful
+
+### ❓ Will this break existing code?
+- **No breaking changes for valid use cases**
+- Minor behavior improvement for multi-type unions (more correct now)
+- The bug being fixed was preventing nullable types from working at all
+
+### ❓ Are the test changes safe?
+- Yes, the removed test was testing INCORRECT behavior
+- New test verifies the actual desired outcome
+- Updated tests reflect more correct type handling
+
+## Recommendation
+
+**✅ APPROVE AND MERGE**
+
+This PR:
+1. ✅ Correctly identifies and fixes the root cause
+2. ✅ Properly defers to google-genai's improved handling
+3. ✅ Includes appropriate test changes
+4. ✅ Handles all edge cases correctly
+5. ✅ Has minimal risk of regressions
+6. ✅ Actually IMPROVES handling of complex union types
+
+## Additional Notes
+
+- The PR author did excellent debugging work (see screenshots in PR description)
+- The fix aligns with how google-genai was designed to work in v1.45.0+
+- This is the cleanest solution - removing conflicting logic rather than adding workarounds
+- The requirement bump to google-genai>=1.45.0 is necessary and correct

test_anyof_unwrap.py

@@ -0,0 +1,43 @@
+"""Test if google-genai properly unwraps anyOf for nullable types."""
+
+from google.genai.types import JSONSchema, Schema
+from pydantic import BaseModel, Field
+import json
+
+class Person(BaseModel):
+    name: str = Field(description="Person's name")
+    age: int | None = Field(description="Person's age", ge=0)
+
+# Generate the Pydantic schema
+pydantic_schema = Person.model_json_schema()
+
+print("=== Original Pydantic Schema ===")
+print(json.dumps(pydantic_schema, indent=2))
+
+# Test: Call google-genai's Schema.from_json_schema directly
+json_schema_obj = JSONSchema(**pydantic_schema)
+gemini_schema = Schema.from_json_schema(
+    json_schema=json_schema_obj,
+    api_option='VERTEX_AI'
+)
+
+print("\n=== Gemini Schema (via google-genai directly) ===")
+print(gemini_schema)
+
+print("\n=== Analyzing 'age' field ===")
+age_schema = gemini_schema.properties['age']
+print(f"Type: {age_schema.type}")
+print(f"Nullable: {age_schema.nullable}")
+print(f"Has any_of: {age_schema.any_of is not None}")
+if age_schema.any_of:
+    print(f"Number of any_of options: {len(age_schema.any_of)}")
+    for i, option in enumerate(age_schema.any_of):
+        option_dict = option.model_dump(exclude_unset=True)
+        print(f"  Option {i}: {option_dict}")
+
+print("\n=== Test Summary ===")
+if age_schema.any_of:
+    print("❌ PROBLEM: anyOf was NOT unwrapped. This will cause Vertex AI error.")
+    print("The schema has both any_of and other fields (type, description, title).")
+else:
+    print("✅ GOOD: anyOf was successfully unwrapped to nullable field.")

test_exact_adk_flow.py

@@ -0,0 +1,75 @@
+"""Test the EXACT flow that ADK uses, including the problematic transformation."""
+
+from google.genai.types import JSONSchema, Schema
+from google.adk.tools._gemini_schema_util import (
+    _sanitize_schema_formats_for_gemini,
+    _dereference_schema,
+    _ExtendedJSONSchema
+)
+from google.adk.utils.variant_utils import get_google_llm_variant
+import json
+
+# This is what Pydantic generates for int | None
+pydantic_schema = {
+    "properties": {
+        "age": {
+            "anyOf": [
+                {"minimum": 0, "type": "integer"},
+                {"type": "null"}
+            ],
+            "description": "Person's age",
+            "title": "Age"
+        }
+    },
+    "type": "object"
+}
+
+print("=== Step 1: Original Pydantic Schema ===")
+print(json.dumps(pydantic_schema, indent=2))
+
+# ADK processing
+dereferenced = _dereference_schema(pydantic_schema)
+print("\n=== Step 2: After _dereference_schema ===")
+print(json.dumps(dereferenced, indent=2))
+
+sanitized = _sanitize_schema_formats_for_gemini(dereferenced)
+print("\n=== Step 3: After _sanitize_schema_formats_for_gemini ===")
+print(json.dumps(sanitized, indent=2))
+
+# The key problem: note the 'age' field after sanitization
+print("\n=== Critical Issue in 'age' field ===")
+age_sanitized = sanitized['properties']['age']
+print(json.dumps(age_sanitized, indent=2))
+print(f"\nNotice: The second element of any_of has type={age_sanitized['any_of'][1]['type']}")
+print("It's ['object', 'null'] instead of just 'null'!")
+print("This is due to _sanitize_schema_type being called on {'type': 'null'}")
+
+# Now convert to Gemini schema
+print("\n=== Step 4: Converting to Gemini Schema ===")
+try:
+    json_schema_obj = _ExtendedJSONSchema.model_validate(sanitized)
+    gemini_schema = Schema.from_json_schema(
+        json_schema=json_schema_obj,
+        api_option=get_google_llm_variant()
+    )
+    print("Gemini Schema for 'age':")
+    age_schema = gemini_schema.properties['age']
+    print(f"  Type: {age_schema.type}")
+    print(f"  Nullable: {age_schema.nullable}")
+    print(f"  any_of: {age_schema.any_of}")
+
+    if age_schema.any_of:
+        print("\n❌ PROBLEM CONFIRMED!")
+        print("The schema was NOT unwrapped because:")
+        print("  The second element is {'type': ['object', 'null']} instead of {'type': 'null'}")
+        print("  So it doesn't match the unwrapping condition")
+        for i, option in enumerate(age_schema.any_of):
+            option_dict = option.model_dump(exclude_unset=True)
+            print(f"  Option {i}: {option_dict}")
+    else:
+        print("\n✅ Schema was unwrapped successfully")
+
+except Exception as e:
+    print(f"Error: {e}")
+    import traceback
+    traceback.print_exc()