Fix Gemini nested tool argument schemas by removing title from $defs

[conradlee]

Problem

When using nested Pydantic models with Gemini without NativeOutput, the model incorrectly treats title fields in nested JSON Schema definitions ($defs) as callable Python functions, resulting in MALFORMED_FUNCTION_CALL errors.

Example: Using these Pydantic models:

class NestedModel(BaseModel):
    name: str
    value: int

class MiddleModel(BaseModel):
    title: str
    items: list[NestedModel]

class TopModel(BaseModel):
    name: str
    pages: list[MiddleModel]

agent = Agent('gemini-2.5-flash', output_type=TopModel)
result = await agent.run('Create example with 2 pages')

Schema sent to Gemini (simplified):

{
  "name": "final_result",
  "parameters_json_schema": {
    "title": "TopModel",
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "pages": {
        "type": "array",
        "items": {"$ref": "#/$defs/MiddleModel"}
      }
    },
    "$defs": {
      "MiddleModel": {
        "title": "MiddleModel",  // ← Gemini treats this as a callable function!
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "items": {
            "type": "array", 
            "items": {"$ref": "#/$defs/NestedModel"}
          }
        }
      },
      "NestedModel": {
        "title": "NestedModel",  // ← Also treated as callable!
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "value": {"type": "integer"}
        }
      }
    }
  }
}

What Gemini incorrectly generates:

MiddleModel(title="Page 1", items=[NestedModel(name="Item", value=1)])

→ Error: Unknown tool name: 'MiddleModel'. Available tools: 'final_result'

What we want Gemini to generate:

{"title": "Page 1", "items": [{"name": "Item", "value": 1}]}

Root Cause

Gemini's function calling parser has a bug where it treats the JSON Schema title field in $defs entries as callable function names, violating the JSON Schema spec where title is purely descriptive metadata. When it encounters "title": "MiddleModel" inside a definition, it thinks "MiddleModel is a function I can call" rather than "this is just metadata describing the schema."

This only affects nested schemas in $defs, not the top-level title (which correctly represents the tool name).

• I have reported this bug in the Google genai SDK repo here: Function calling incorrectly interprets title fields in nested JSON schemas as callable functions googleapis/python-genai#1732

Solution

Remove title fields from nested schemas (those in $defs) while preserving:

• $ref/$defs structure (for better schema organization)
• Top-level title (needed for the function declaration name)

Transformed schema (after fix):

{
  "$defs": {
    "MiddleModel": {
      // "title" removed!
      "type": "object",
      "properties": {...}
    },
    "NestedModel": {
      // "title" removed!
      "type": "object",
      "properties": {...}
    }
  },
  "title": "TopModel",  // ← Kept at root level
  ...
}

Key insight: We initially thought we needed to inline all $ref definitions, but testing with real API calls revealed that Gemini can handle $ref/$defs correctly—the problem is only with the title fields. This makes the fix much simpler and cleaner.

Implementation

Modified GoogleJsonSchemaTransformer.transform() to detect and remove title from nested schemas:

# Remove 'title' from nested schemas - Gemini treats these as callable function names
if self.defs and 'title' in schema:
    if schema.get('title') in self.defs:  # Is this a $defs entry?
        schema.pop('title', None)

Testing

• Added test_google_nested_models_without_native_output (reproduces the exact failing case from Nested Pydantic Models Treated as Tool Calls Instead of Structured Output for Gemini Models #3483)
• Added test_google_nested_models_with_native_output (verifies the NativeOutput workaround)
• All 81 Google model tests pass
• Verified with real Gemini API calls using the simplified fix

Related Issues

• Fixes Nested Pydantic Models Treated as Tool Calls Instead of Structured Output for Gemini Models #3483
• Reported to Google SDK: Function calling incorrectly interprets title fields in nested JSON schemas as callable functions googleapis/python-genai#1732

[conradlee]

Thanks for the speedy review @DouweM!:

1. Always dropping title: I've updated the code to always remove title from all schemas I agree that this is simpler and avoids the edge case where a user might have customized the title.

My understanding is that when pydanitc models are transformed into json schemas, the title field is quite redundant:

• For root/nested models: The title is just the class name, which is already captured in the $defs key
• For properties: The title is just the capitalized field name, which is already captured in the property key

Is that right? Then we don't have to feel bad about stripping titles.

2. Removing customize_request_parameters: Yes, as I mentioned above, this was just some leftover cruft. Sorry about that.