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: #880
References: #827, #854, google/adk-python#2733, google/adk-python#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!

[koverholt]

Thanks for the PR! This page is in a much different format than #785, and it's difficult to follow the recommendations on this page due to its verbose length and redundancy.

• The Related Issues section is not needed
• The metadata at the bottom of the document is not needed
• The Additional Resources links are redundant or not needed
• The Migration Checklist, Quick Reference Card, Python Version Compatibility, Required Patterns, and Troubleshooting sections are redundant
• The Common Errors and Fixes section could be added to the best practices page proposed in #785.
• The Complex Type Patterns would likely be better represented as code samples on https://google.github.io/adk-docs/tools/function-tools/
• The content in the Validation and Testing section would likely fit best as its own page under Function Tools

For these reasons, my proposal is to:

1. Close this PR and instead add a few more sections related to type annotations to the best practices page proposed in #785.
2. Other, smaller PRs can be opened to add tips and guidance to the existing Function Tools Overview page as needed.

cc @joefernandez

[jpantsjoha]

Good point. Let me tackle this now.

I'll close this PR and integrate the core type annotation patterns into google/adk-python#785 after it merges. Much cleaner approach.

Cheers, JP