fix(kosong): strip JSON Schema metadata from Google GenAI tool parameters - #739

There is a one-line version of this that removes the whole class of failure instead of the four keys, and I think it's worth considering before this lands: pass the schema to parameters_json_schema= rather than parameters=.

FunctionDeclaration has both fields. parameters= is the narrow OpenAPI-style Schema proto (extra='forbid', which is what raises here); parameters_json_schema= is the JSON-Schema field, and it takes the schema verbatim — no stripping, no rewriting. Measured on google-genai==2.17.0 with an Exa-shaped schema carrying every keyword at once:

RAW = {"$schema": "http://json-schema.org/draft-07/schema#", "type": "object",
       "properties": {"a": {"type": ["string", "null"]},
                      "c": {"type": "integer", "exclusiveMinimum": 0},
                      "d": {"type": "array", "prefixItems": [{"type": "integer"}]}}}

FunctionDeclaration(name="t", parameters=RAW)              # 6 validation errors
FunctionDeclaration(name="t", parameters_json_schema=RAW)  # accepted, byte-identical

This isn't an obscure corner — it's what the JS client already does for you. @google/genai checks for a top-level $schema and, when it finds one, routes the declaration to parametersJsonSchema and sends it unmodified. So the key that's crashing the Python client is the same key that tells the JS client to use the field that accepts everything. Python has no such auto-routing (there is no $schema handling anywhere in the package), which is why this only shows up here.

Two things about the current patch that I'd want on the record either way, both measured against the diff as written:

1. The strip is top-level only. tool.parameters.items() isn't recursive, and $comment / examples / $id almost always appear on individual properties rather than at the root. Running the PR's exact transform:

PR-fixed, top-level $schema     OK          <- the reported Exa case
PR-fixed, nested $comment       REJECTED    parameters.properties.q.$comment
PR-fixed, nested examples       REJECTED    parameters.properties.q.examples
PR-fixed, nested $id            REJECTED    parameters.properties.q.$id

2. Even a recursive strip leaves about a dozen more, and most of them have no $. Same transform, one keyword per run:

type: ["string","null"]  REJECTED    prefixItems      REJECTED
exclusiveMinimum         REJECTED    uniqueItems      REJECTED
enum: [1, 2]             REJECTED    const            REJECTED
oneOf                    REJECTED    anyOf            OK  (control)

plus array-form items, patternProperties, propertyNames, allOf and not. A $-prefix heuristic catches none of these, and MCP servers emit them routinely.

The two that matter most can't be fixed by stripping at all, because deleting them destroys the parameter rather than sanitising it:

• type: ["string", "null"] — the standard spelling for an optional parameter. Dropping type leaves the model with no idea what to send. The lossless rewrite is {"type": "string", "nullable": true} — nullable is a real Schema field, verified accepted. (This is also exactly what @google/genai does silently on the narrow path.)
• prefixItems: [int, int] / array-form items — dropping it turns "exactly two integers" into "an array of anything, any length", which returns a 200 and garbage. Lossless when the positions share a type: items: {...} + minItems/maxItems, both accepted.

So if the strip approach is preferred over the field switch, it needs to be a recursive rewrite, not a recursive delete.

Last thing, and it makes any of these testable: FunctionDeclaration(...) raises offline with no API key and no network, so the repro in #734 is already a CI test. Iterating a table of keyword → schema through it pins the accepted set in a few seconds and catches the next SDK version that moves the boundary.

(One surface caveat if this pattern gets reused elsewhere: the same SDK does inline $ref/$defs for you on response_schema, but not on FunctionDeclaration.parameters, where a $ref is rejected outright. Doesn't affect this PR — deref_json_schema() has already run — but the behaviour isn't uniform across the SDK's surfaces.)