docs(guides): add type annotation best practices guide for function tools

[jpantsjoha]

Summary

Comprehensive guide addressing type annotation issues with Gemini API schema validation. This guide prevents the 3+ hour debugging cycles developers experience when using function tools with incomplete type annotations.

Problem Solved

Developers are hitting schema validation failures (400 Bad Request errors) when using function tools due to:

• Using bare list/dict instead of List[T]/Dict[K,V]
• Modern | None syntax not supported (despite docs claiming it works)
• Confusion between Python 3.10+ syntax and ADK/Gemini requirements

Real-world impact: Our team (DISC - MultiAgent RFQ Project) lost 3+ hours debugging this exact issue in production.

Related Issues (adk-python)

• #1634 - int | None union syntax fails to parse
• #2925 - Modern Union type not supported
• #2733 - Enum support in input schemas
• #398 - Enum types in function parameters
• #3214 - Documentation proposal issue

What This PR Adds

New Content (docs/guides/tool-type-annotations.md - 580 lines)

1. Introduction: Why type annotations matter for Gemini API
2. Required Patterns: What works TODAY
3. Common Errors & Fixes: Before/after examples with 400 errors
4. Python Version Compatibility: 3.9-3.12 guidance
5. Complex Type Patterns: Nested structures, Union types
6. Enum Workarounds: Using Literal
7. Validation & Testing: mypy integration
8. Migration Checklist: Update existing tools
9. Quick Reference Card: Cheat sheet
10. Troubleshooting: Error patterns and fixes

Updates

• docs/tools/function-tools.md: Warning callout
• mkdocs.yml: Navigation entry

Testing

• ✅ mkdocs build --strict passes
• ✅ All examples validated with Gemini 2.0 Flash
• ✅ Tested against DISC production code

Impact

Before: 3+ hours debugging, scattered workarounds
After: Clear patterns, prevent errors, reduce debugging time

Community Validation

• 7 related issues (5 OPEN)
• Multiple independent reports
• Production blocker confirmed

---

Resolves: google/adk-python#3214
References: google/adk-python#1634, #2925, #2733, #398

[jpantsjoha]

Hi team! 👋

Just a friendly check-in on this PR. It's been about 5 days since submission and I wanted to see if there's anything I can adjust or clarify to help with the review process.

Happy to make any changes needed. Thanks for your time reviewing community contributions!