ValueError
ValueError: Invalid tool_config response from Gemini API
Stack trace
Traceback (most recent call last):
File "app.py", line 42, in <module>
response = model.generate_content(user_input, tools=tools)
File "/site-packages/google/generativeai/generative_models.py", line 156, in generate_content
self._prepare_tools(tools)
File "/site-packages/google/generativeai/generative_models.py", line 203, in _prepare_tools
self._validate_tool_config(tool_config)
File "/site-packages/google/generativeai/generative_models.py", line 218, in _validate_tool_config
raise ValueError(f"Invalid tool_config: {error_detail}")
ValueError: Invalid tool_config: Tool 'search' missing required field 'description' in parameters schema Why it happens
Gemini's function calling API requires tool definitions to conform to a strict JSON schema: each tool must have a name, description, and a parameters object with type and properties fields. When you pass tools missing descriptions, nested schema fields without type definitions, or parameter names that don't match the function signature, the API rejects the tool_config before execution. This validation happens server-side after the client sends the request, making the error appear after your code looks correct.
Detection
Before calling generate_content with tools, validate each tool definition against Gemini's schema requirements: verify every parameter has a 'type' field, all required fields have descriptions, and nested objects include 'properties'. Log the raw tool_config JSON before sending to catch structural errors early.
Causes & fixes
Missing 'description' field in tool parameters schema or in the tool itself
Add a 'description' string to every tool and every parameter in the parameters schema. Example: {'name': 'search', 'description': 'Search the web', 'parameters': {'type': 'object', 'properties': {'query': {'type': 'string', 'description': 'The search query'}}, 'required': ['query']}}
Parameters schema missing 'type' field at the object level or in nested properties
Ensure parameters is always {'type': 'object', 'properties': {...}, 'required': [...]}, and each property has 'type' defined. Never omit 'type': 'object' at the top level of parameters.
Using Pydantic or dataclass models without converting to JSON schema first
Use genai.protos.Tool to wrap function definitions, or convert Pydantic models to JSON schema with model.model_json_schema() before passing to tools parameter.
Tool names or parameter names contain spaces, special characters, or don't match the actual function signature
Ensure tool names are alphanumeric with underscores only. Parameter names must exactly match the function definition. Use snake_case (search_query, not search-query or 'search query').
Code: broken vs fixed
import os
import google.generativeai as genai
genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.0-flash')
# BROKEN: Missing 'description' in parameters, incomplete schema
tools = [
{
'name': 'search',
'parameters': {
'properties': {
'query': {'type': 'string'} # Missing description
},
'required': ['query']
# Missing 'type': 'object' at parameters level
}
# Missing tool-level description
}
]
user_input = 'Find information about Python'
response = model.generate_content(user_input, tools=tools) # ValueError raised here
print(response.text)import os
import google.generativeai as genai
genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.0-flash')
# FIXED: Complete tool schema with all required fields
tools = [
{
'name': 'search',
'description': 'Search the web for information', # Added tool description
'parameters': {
'type': 'object', # Added required type field
'properties': {
'query': {
'type': 'string',
'description': 'The search query string' # Added parameter description
}
},
'required': ['query']
}
}
]
user_input = 'Find information about Python'
response = model.generate_content(user_input, tools=tools)
print(f'Response: {response.text}')Workaround
If you cannot modify the tool definitions immediately, wrap the generate_content call in try/except ValueError, catch the validation error, extract the tool name from the error message, and rebuild that specific tool with all required fields before retrying. Alternatively, use Gemini's built-in function declaration helpers from genai.protos instead of manual dicts.
Prevention
Define tools using genai.protos.Tool or a schema validation library (pydantic, jsonschema) before runtime. Create a helper function that takes a Python function or Pydantic model and auto-generates Gemini-compliant tool_config, ensuring descriptions, types, and required fields are always present. Test tool definitions against the JSON schema validator before deploy.