Forced function calling is broken in Gemini, in three different ways

Three undocumented schema budgets in Gemini's tool API cause INVALID_ARGUMENT failures, mostly in ANY mode.

Gemini has several quirks which made working with it difficult. One of the compelling pros in building agent harness around pure function calls is that it makes everything very homogenuous. Each model action is a function call - it does not matter whether the call is emitting thoughts or producing it’s final output after a round of function call. Such setup makes instrumentation easy and codebase clean. It can be enabled in Gemini using the ANY option for the function calling mode, which forces the model to only call functions.

While elegant solution, in practice it exposed multiple shortcomings in the current Gemini’s API implementation and clearly showed that this is off the beaten path, which gets much less developer attention and at scale simply breaks.

I spent several hours reproing, debugging and trying to minimize the examples which lead to the broken behavior to create actionable bug reports, but ultimately, for anyone building anything serious, I would highly discourage using anything off the beaten path even if documented by the APIs. ANY is an example feature which falls in this bracket.

What follows is a collection of issues which you may hit, if you choose to run with ANY.

Gemini’s tool schema validator has three undocumented limits. Past a certain scale, valid tool definitions return INVALID_ARGUMENT with no error body. ANY mode (forced function calling) hits all, AUTO just one.

Enum complexity has a length-weighted budget

python-genai/#2133

ANY mode imposes a budget on the aggregate complexity of all enum values across all tool schemas, weighted by per-value length.

Per-value lengthANY mode passes atFails by
1 word400+ values—
2 wordsup to ~240~240
4 wordsup to ~120~120

Too many enum values breaks schemas.

maxItems has a cumulative cap

python-genai/#2170

The sum of all maxItems values across all properties of all tool schemas must stay below ~960. Above that, both ANY and AUTO mode fail.

Tool declaration payload has a hidden size cap

python-genai/#2293

ANY mode fails past roughly 77 KB of combined tool declaration JSON. AUTO mode passes the identical request. AI Studio’s UI occasionally surfaces the underlying error:

Constraint is too tall: 6336 (vs max of 5888)

The “constraint height” budget is undocumented. There’s no public mapping from observable schema metrics to constraint-height units. The same schemas work just fine in the AUTO mode.

Workarounds

  1. Move enum values to descriptions. enum: ["low", "medium", "high"] → description: "Priority level. One of: low, medium, high."
  2. Validate tool calls in the agent loop. Enforce constraints on call return rather than at the schema layer.
  3. Reserve strict enums for small, critical fields.
  4. Avoid maxItems unless required. Validate length in the agent loop instead.
  5. Monitor cumulative tool declaration size. Expect ANY mode failures past ~80 KB.