Gemini: every request fails with HTTP 400 when a tool schema contains $ref / $defs / additionalProperties

[angel12538]

Summary

When a session has any tool loaded whose parameters JSON Schema uses $ref, $defs, or additionalProperties, every request to a Google Gemini model fails with:

HTTP 400
{"error":{"code":400,"message":"Request contains an invalid argument.","status":"INVALID_ARGUMENT"}}

Because the full tool catalog is re-sent on each turn, the session becomes completely unusable on that provider — the failure is unrelated to the user's message content. Switching the same conversation to an OpenAI-compatible provider (deepseek-account/deepseek-flash) works normally, which shows the tool schemas are valid JSON Schema; the incompatibility is specific to the Gemini request path in DSH.

DSH appears to forward MCP/built-in tool schemas to Gemini verbatim. Gemini's functionDeclarations[].parameters only accepts an OpenAPI 3.0 subset and rejects unknown keys outright.

Related: #10167 reports the same $ref family on a different validation path — a $ref inside function_response.response, rejected with does not match to a display_name in the function_response.parts. This report covers the tool declaration path (functionDeclarations[].parameters), which fails earlier and more broadly: the request is rejected before any tool is ever invoked, so a session never even gets to the point #10167 describes. A fix that only serializes tool results as opaque text will not help here; the declarations themselves must also be sanitized.

Environment

Item	Value
DSH	0.2.1-rc.3 (nightly, desktop profile, Windows x64)
Endpoint	https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent
Model	gemini-3.8-flash, also reproduced on gemini-3.7-flash
Protocol	api: openai-completions-style provider entry under @deepseek-ai/dsh-llm-pi-ai, google: with default baseURL
Tools mounted	built-in tools + @deepseek-ai/dsh-mcp-client (REA MCP server) + zhipu_search_api

Minimal reproduction

Send a generateContent request directly to the Gemini endpoint, changing only the tool schema. All four requests use the same model, key, and contents.

// A: no tools                                  -> HTTP 200
{"contents":[{"role":"user","parts":[{"text":"hi"}]}]}

// B: flat schema                               -> HTTP 200
{"contents":[...],"tools":[{"functionDeclarations":[{
  "name":"ping","description":"ping",
  "parameters":{"type":"object","properties":{"msg":{"type":"string"}}}}]}]}

// C: schema containing $ref and $defs          -> HTTP 400
{"contents":[...],"tools":[{"functionDeclarations":[{
  "name":"probe","description":"probe",
  "parameters":{
    "type":"object",
    "properties":{"a":{"$ref":"#/$defs/X"}},
    "$defs":{"X":{"type":"string"}}}}]}]}

// D: schema containing additionalProperties    -> HTTP 400
{"contents":[...],"tools":[{"functionDeclarations":[{
  "name":"probe2","description":"probe2",
  "parameters":{
    "type":"object",
    "properties":{"a":{"type":"string"}},
    "additionalProperties":false}}]}]}

One-liner curl for the failing case:

curl -sS -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"hi"}]}],"tools":[{"functionDeclarations":[{"name":"probe","description":"probe","parameters":{"type":"object","properties":{"a":{"$ref":"#/$defs/X"}},"$defs":{"X":{"type":"string"}}}}]}]}'

Remove the tools array (or flatten the schema) and the same request returns 200.

Observed matrix

Schema keyword	Result
(no tools at all)	200 OK
plain object / properties / string	200 OK
$ref	400 Unknown name "$ref"
$defs	400 Unknown name "$defs"
additionalProperties	400 Unknown name "additionalProperties"
oneOf	200 OK

anyOf / allOf / enum+const were attempted but not conclusively captured in this run — treat those as untested.

Raw error payloads

400  Invalid JSON payload received. Unknown name "$ref" at
     'tools[0].function_declarations[0].parameters.properties[0].value':
     Cannot find field.

400  Invalid JSON payload received. Unknown name "$defs" at
     'tools[0].function_declarations[0].parameters':
     Cannot find field.

400  Invalid JSON payload received. Unknown name "additionalProperties" at
     'tools[0].function_declarations[0].parameters':
     Cannot find field.

The message surfaced in the DSH UI (Request contains an invalid argument.) is Gemini's generic wrapper; the details[] / field-level reason above is what actually identifies the culprit.

Why it breaks the whole session

DSH re-sends the complete tool catalog on every turn. As soon as one loaded tool carries $ref, $defs, or additionalProperties, the payload is rejected before inference — so the failure is constant, not content-dependent.

In this environment the main contributor is the REA MCP server (@deepseek-ai/dsh-mcp-client), whose schemas use $defs + $ref heavily. However, removing that MCP server is not a full workaround, because some built-in tool schemas also emit additionalProperties (e.g. the workflow tool's args field).

Suggested fix

Either of these would resolve it:

1. Sanitize schemas on the Gemini path (preferred). Before building functionDeclarations, walk each tool's parameters and:

   • inline every $ref / $defs (dereference),
   • strip additionalProperties,
   • drop or narrow any other unsupported keyword,
   • optionally replace the whole schema with a permissive {type:"object", additionalProperties:true} fallback if dereferencing cannot converge (recursive schemas).

   Note: 0.2.1-rc.3 contains no such sanitizer — symbol scan of app.asar for pruneSchema, sanitizeSchema, dereferenceSchema, resolveSchemaRefs returned nothing.

2. Expose per-provider tool filtering so a provider can exclude incompatible tools (e.g. mcp__rea__*) without unloading the MCP server globally. The only toolFilter found in app.asar is ContinuableSubagentDescriptorData.toolFilter?: ToolRestriction, which is sub-agent scoped and does not affect the outbound Gemini payload.

Expected behavior

A Google Gemini model should be selectable in a session that has MCP tools mounted, with schemas downgraded to what the API accepts — or, at minimum, DSH should surface the field-level details[] reason ("Unknown name $defs") instead of only the generic Request contains an invalid argument., so users can tell a model/provider incompatibility apart from a bad API key or a network failure.

---

中文摘要

现象：任何挂了复杂 MCP 工具的会话，切到 Google Gemini 线路后，每一条消息都返回 400 INVALID_ARGUMENT / Request contains an invalid argument.，与消息内容无关；切到 DeepSeek 线路即正常。

根因：DSH 把工具的完整 JSON Schema 原样发给 Gemini，而 Gemini 的 functionDeclarations[].parameters 只接受 OpenAPI 3.0 子集，遇到 $ref、$defs、additionalProperties 会直接 Cannot find field 拒绝。工具清单每轮都发，所以必然整场失败。

已实测：无工具 / 扁平 schema / oneOf → 200；$ref / $defs / additionalProperties → 400。

建议：在 Gemini 请求路径上对 schema 做降级（解引用 $ref/$defs、删 additionalProperties），或提供按 provider 过滤工具的能力。当前 0.2.1-rc.3 两者都没有。

[argszero]

The declaration path this report measures now has a plugin, and your cases C and D are what it removes.

@argszero/dsh-mcp-schema-normalizer 0.2.0 — source — shadows register on the tools service instance and rewrites an MCP tool's parameters before the registration is forwarded. It already narrowed union-typed parameters; 0.2.0 adds the three keywords you tested:

• inline-ref replaces a local $ref with the subschema it names, and prune-defs drops a $defs/definitions table nothing outside it points into any more (the REA MCP server shape);
• drop-additional-properties removes the keyword, whichever shape it has.

Mount it before the row that connects your MCP servers:

- insert:
    - id: mcp-schema-normalizer
      name: '@argszero/dsh-mcp-schema-normalizer'
      config: { mode: observe }   # observe first: reports what normalize would change, changes nothing

Three things I would rather state than let you discover:

It is not on the registry yet. 0.2.0 is committed on the repository's main (b5be5f2); npm still serves 0.1.1, which does not carry these two rules. So read the source link for the fix and treat the install line as "when the publish lands" — I would not have you install 0.1.1 and conclude the plugin does not work.

Your second half stands, and I verified it here instead of taking it on trust. The workflow tool's own parameters do carry additionalProperties: true (packages/workflow/tool-workflow/src/index.ts:343 and :355), so removing the MCP server is indeed not a workaround. That declaration is core-authored, and this plugin's selector names MCP servers (mcp__<server>__<tool>), so a built-in tool's keyword is not in its scope. For a session whose only offender is a built-in, the repair belongs where the schema is written, not in a plugin.

A plugin rewrites what the model is told, not what the provider accepts. A ToolDefinition here carries no validator — an MCP tool's definition is built from the server's inputSchema and the server validates its own arguments — so inlining a $ref is a different way of saying the same thing to the only party that reads the declaration. Your suggestion 1 (sanitize on the Gemini request path) is still the right core-side fix and still worth making: it also reaches the function_response half in #10167, which is outside this seam entirely. Likewise, an unresolvable reference (an external URL, a dangling pointer, a cycle, anything past the expansion budget) is left exactly as the server wrote it and named in snapshot().unresolvedRefs — this plugin resolves offline only and invents no target.

The field-level details[] you ask for in "Expected behavior" is a separate, cheap fix: the message the UI shows is Gemini's generic wrapper, and the Unknown name "$defs" line is already in the response body.

[angel12538]

@argszero — installed 0.2.1 (945e079) and ran it against a real 305-tool session. Numbers below, since that is what you asked to see rather than trust.

It does work on the MCP side

Measured from the session log's request/header.tools (what DSH actually sends), before vs. after mounting with mode: normalize:

	tools	$ref	$defs	additionalProperties
before	280	745	169	1422
after	305	0	0	12

The 207 mcp__rea__* tools contributed 745 / 169 / 1413 of those, and all of it is gone. The remaining 12 come from eight non-MCP tools: ask_user_question, workflow, ego_cdp, ego_http, present, todo_write, chatgpt_connectors_call, codex_image_generate.

Two things still reject the request

I fed the real post-normalisation schemas straight to gemini-3.8-flash:

subject	result	reason
ask_user_question	400	additionalProperties
workflow	400	additionalProperties
one REA tool	400	$schema, examples
first 40 tools	400	both of the above

So, two findings:

1. Your prediction about the built-in half held exactly. workflow's own parameters do carry additionalProperties, and your selector (mcp__<server>__<tool>) cannot reach a core-authored declaration. Confirmed by measurement, not taken on trust.

2. A gap in the rule set. Even after $ref / $defs / additionalProperties are removed, an REA tool still 400s — on $schema and examples. Those are two more keys outside the OpenAPI subset Gemini accepts. If the plugin is meant to make the declaration path survivable on its own, they would need rules too — or a stricter posture still, something like "emit only keys from the allowed vocabulary".

Limitation of my run

I could not finish the obvious follow-up — strip everything and see whether it finally returns 200. The endpoint started answering 429, then User location is not supported for the API use (my egress is unstable). So the table above is solid; the threshold — exactly how much has to go — is still open. I would rather say that than round it up.

I agree with the seam you drew: MCP declarations belong to the plugin, built-in declarations belong to core, and #10167's function_response half belongs to core as well. My report #10904 asked for the core-side sanitize for precisely that reason.

[Sultan57git]

This comes up a lot with MCP tools, because many servers generate their schemas from Pydantic or Zod, and those emit $defs/$ref and additionalProperties. Since the whole tool catalog is re-sent every turn, one bad tool breaks the whole session. A fix that has worked for others is to clean the schema in the Gemini request path only. Resolve each $ref inline from $defs (and stop at a fixed depth so recursive refs can't loop forever), then remove the keywords Gemini rejects. Leave the original schema unchanged for the other providers. It would also help to drop just the offending tool with a warning rather than fail the whole request. Gemini's newer API docs describe a JSON-Schema parameters field that may accept more keywords, so check the current docs before relying on it.

[argszero]

Both of your remaining findings come from the same three places, so here is the chain rather than another rule. Line numbers are at 22ddee3792.

1. Nothing between a tool and the adapter filters a schema.

• packages/llm/llm/src/types.ts:548 puts tools?: ToolSchema[] on the outgoing request, and :501 types parameters as a plain Record<string, unknown> — at that layer the schema is an opaque object.
• packages/llm/llm-pi-ai/src/context.ts:132 is return { name: tool.name, description: tool.description, parameters: tool.parameters }. Verbatim: no dereference, no key filtering, no per-protocol copy.
• packages/llm/llm-pi-ai/src/provider.ts:47-51 — the protocols a route may name are openai-completions, openai-responses and anthropic-messages. There is no Gemini protocol, so a google route (it exists in provider-data.generated.ts:21, with defaultBaseURL: https://generativelanguage.googleapis.com/v1beta) is necessarily composed in one of those three dialects — yours is openai-completions — and Google translates it. That is why the 400 quotes tools[0].function_declarations[0].parameters: that path exists only after Google's own translation, which is also why the offending key is named there and nowhere in the generic wrapper DSH surfaces.

2. The twelve survivors are structural, not a rule you and I missed. packages/core/tools/src/schema.ts:368-373: an author declaring type: 'object' must state additionalProperties: true|false — it is required, not optional — and the compiler copies it into the compiled schema. projectToolSchema (:641-645) then emits that object as the request's parameters. So workflow, todo_write, present and the rest carry the key because core's own schema language requires it, and a selector naming mcp__<server>__<tool> cannot reach a core-authored declaration at any correctness level. In the other direction, the MCP bridge puts the server's inputSchema on the definition as-is (packages/mcp/mcp-client/src/tools.ts:234, parameters: inputSchema), so $schema and examples reach the wire exactly as the server wrote them — nothing between that line and the adapter rewrites them. (For the record, the additionalProperties: false at mcp-client/src/tools.ts:259 is inside createOutput and belongs to a tool's output schema, which never enters the request; it is not a source of your 400.)

3. A request-time listener cannot finish this either. llm/stream (packages/llm/llm/src/index.ts:75) does hand a listener the whole GenerateOptions, provider included, once per call — so the schemas and the route are both visible there. But the same declaration says a loop-built request "arrives deep-frozen (mutation throws) … listeners read it, never rewrite it" (:67-72), and next() takes no replacement options. Rewriting schemas per route is therefore not a seam that exists today: a listener can observe the schemas, not substitute them.

What follows for the fix. It belongs where the request is serialized for one route — a Gemini normalization step in llm-pi-ai, ahead of the request leaving — or in the schema language itself, if core wants one canonical additionalProperties posture. Both are core-side; neither is reachable from a plugin, which is the honest boundary on what your mounted normalizer can cover.

On $schema and examples: confirmed, and it still holds at HEAD 945e079 — the rule set there is inline-ref and drop-additional-properties, nothing else, so both keys pass straight through. One-off rules are also the wrong shape: keyword-by-keyword deletion keeps finding the next key, while an allowlist posture ("emit only keys in the accepted vocabulary") is the version that terminates.

What I have not measured, so will not claim: I have not run the normalizer against a live generateContent endpoint — there is no usable key on this host, and your own egress is what produced the 429s. Your table is the only evidence in this thread, and it says the declaration path does not yet survive Gemini on its own.

On the threshold you could not finish: it should not need a bisect. Each rejection names the offending field, so one request per tool — each tool sent alone — tells you which tools are survivable, and the union of the failing ones is the set that has to go.

[Sultan57git]

Thanks, this chain is more useful than another rule. It shows the schema is an opaque object from types.ts down to the adapter, so nothing in between is positioned to fix it. That points to one sanitising step per provider protocol, applied at the adapter boundary. It should dereference $ref/$defs and drop unsupported keys, and it should be tested with a fixture schema for each provider. That keeps tool authors from having to write provider-specific schemas.