docs: Improve documentation for type annotations with Gemini API schema validation

## Problem

Developers are experiencing **schema validation failures** (400 Bad Request errors) when using function tools with Gemini API due to unclear or incomplete type annotation requirements. This is causing production blockers and developer frustration across the community.

### Personal Experience
Our team lost **3+ hours debugging** type annotation issues during development of the DISC - MultiAgent RFQ Project. We discovered that type annotations that work perfectly in standard Python fail when used with ADK function tools due to Gemini API schema generation requirements.

**Example from DISC project**:
```python
# ❌ This caused 400 Bad Request from Gemini API
def process_data(items: list) -> dict:
"""Process data items."""
pass
# Error: Schema validation failed - array missing 'items' field

# ✅ This worked
from typing import List, Dict, Any
def process_data(items: List[dict]) -> Dict[str, Any]:
"""Process data items."""
return {"processed": len(items)}
```

This pattern is **not documented anywhere** in the official ADK guides, leading to repeated debugging cycles across the community.

## Related Issues

Multiple community members have reported similar problems:

### Active Issues (OPEN)
- **#1634** - "int | None union syntax fails to parse in function parameters" (3 comments, active discussion)
- **#2925** - "Allow modern Union type for FunctionTool" (docs claim `| None` syntax works, but it doesn't)
- **#2733** - "Allow enums in input schemas"
- **#398** - "Support Enum type for function tool args" (reported 6 months ago, still open)

### Closed Issues (Workarounds Not Documented)
- **#55** - "Union types don't work?" (400 errors with `Union[int, str]`)
- **#745** - "ADK LlmAgent/Gemini: Tool Parameter Error & 400 on Tool Failure"
- **#1169** - "More clear error message for missing param type with default with Gemini"

## Root Cause

The Gemini API generates OpenAPI schemas from Python type annotations. When annotations are incomplete or use unsupported syntax, schema generation fails with cryptic errors:
- Bare `list`/`dict` → missing 'items' field error
- Modern `| None` syntax → "Failed to parse parameter" error
- Missing type hints → 400 INVALID_ARGUMENT from Gemini

## Proposed Solution

Create a comprehensive **Type Annotation Best Practices Guide** in `adk-docs` covering:

1. **Why Type Annotations Matter**: Explain Gemini API schema generation
2. **Required Patterns**: Document what works TODAY
- `List[T]` vs `list` (bare collections fail)
- `Optional[T]` vs `T | None` (modern syntax not supported yet)
- `Dict[K, V]` vs `dict` (missing schema fields)
3. **Common Errors & Fixes**: Before/after examples with actual error messages
4. **Python Version Compatibility**: Clarify Python 3.10+ syntax vs ADK requirements
5. **Enum Workarounds**: Document `Literal` pattern until native support added
6. **Migration Checklist**: Help developers update existing tools
7. **Quick Reference Card**: Cheat sheet for common patterns

### Proposed File Structure
```
adk-docs/
├── docs/
│ ├── guides/
│ │ └── tool-type-annotations.md # NEW comprehensive guide (~580 lines)
│ └── tools/
│ └── function-tools.md # UPDATE with warning and link
└── mkdocs.yml # UPDATE navigation
```

## Impact

### Current State (Without Guide)
- Developers hitting schema validation errors repeatedly
- 3+ hours lost per developer debugging type annotations
- Documentation claims `| None` works but implementation doesn't
- Workarounds scattered across closed issues, not discoverable

### Expected Outcome (With Guide)
- Prevent new users from hitting schema validation errors
- Document working patterns and known limitations
- Clarify discrepancy between Python 3.10+ syntax and ADK requirements
- Reduce time spent debugging type annotation issues
- Improve documentation credibility (align docs with reality)

## Community Validation

- **7 related issues** (4 OPEN, 3 CLOSED) requesting this guidance
- **Multiple developers** reporting identical problems independently
- **Production blocker**: Schema validation failures prevent agent execution
- **Fresh reports**: Issues google/adk-docs#827 and google/adk-docs#854 have recent activity

## Offer to Contribute

I've drafted a comprehensive guide and am ready to submit a PR to `adk-docs`. The guide includes:
- Tested code examples (validated with Gemini 2.0 Flash)
- Before/after comparisons for common errors
- Migration checklist for updating existing code
- Cross-references from existing documentation
- Quick reference card for common patterns

Please advise if this approach is acceptable and if there are any specific areas you'd like emphasized.

---

**References**:
- Real-world validation: DISC - MultiAgent RFQ Project
- Community issues: google/adk-docs#827, google/adk-docs#854, google/adk-python#2733, google/adk-python#398, google/adk-python#55, google/adk-python#745, google/adk-python#1169
- Target: `adk-docs/docs/guides/tool-type-annotations.md`