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

[jpantsjoha]

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:

# ❌ 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)

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

Closed Issues (Workarounds Not Documented)

• Union types don't work? #55 - "Union types don't work?" (400 errors with Union[int, str])
• ADK LlmAgent/Gemini: Tool Parameter Error & 400 on Tool Failure #745 - "ADK LlmAgent/Gemini: Tool Parameter Error & 400 on Tool Failure"
• More clear error message for missing param type with default with Gemini #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 int | None union syntax fails to parse in function parameters despite documented support #1634 and Allow modern Union type for FunctionTool #2925 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: int | None union syntax fails to parse in function parameters despite documented support #1634, Allow modern Union type for FunctionTool #2925, Allow enums in input schemas #2733, Support Enum type for function tool args #398, Union types don't work? #55, ADK LlmAgent/Gemini: Tool Parameter Error & 400 on Tool Failure #745, More clear error message for missing param type with default with Gemini #1169
• Target: adk-docs/docs/guides/tool-type-annotations.md