Fix 400 INVALID_ARGUMENT: Google Gemini GenAI API MCP Schema

When working with Google Gemini GenAI API (MCP wrapper or similar integrations), a 400 INVALID_ARGUMENT is usually a schema mismatch: the API expects a specific JSON Schema shape for function declarations and parameters, and one or more fields (often a keywords array) are missing required property types. This guide walks through the root causes, a concrete schema fix example, validation/testing steps, and preventative best practices. It also includes direct links to a sample MCP schema and a reproducible fix for quick reference.

For a concrete reference and example schema that illustrates this issue, see the MCP sample and discussion here: Google Gemini GenAI API error and MCP code schema.

What causes 400 INVALID_ARGUMENT in Gemini GenAI API?

HTTP 400 INVALID_ARGUMENT from the Gemini GenAI API typically indicates that the request payload is syntactically valid JSON but semantically invalid according to the API’s schema expectations. The API validates the “functionDeclaration” and its “parameters” field using JSON Schema rules; if required properties, types, or structure differ, the server rejects the request with INVALID_ARGUMENT instead of processing it. In practice, this often shows up when arrays are sent as strings, objects are missing required keys, or the “type” attribute is omitted entirely.

One recurring pattern is a missing or incorrectly defined functionDeclaration.parameters.keywords. Developers sometimes pass keywords as a plain comma-separated string, or as an array without specifying that the parameter’s JSON Schema includes “type”:”array” and “items”:{“type”:”string”}. The API’s validator enforces explicit types; implicit assumptions (e.g., “it looks like an array”) will fail.

Another cause is embedding the JSON Schema incorrectly (for example, passing a stringified schema where the API expects a JSON object or vice versa). Also check for subtle issues like boolean vs. string values, extraProperties policies, and mismatched capitalization in property names. Logs typically show a succinct INVALID_ARGUMENT message; you must inspect server-side schema validation errors or run a local validator to get the full failure detail.

Diagnosing MCP code schema issue and functionDeclaration.parameters.keywords

Start by reproducing the smallest failing request. Remove optional fields and send only the functionDeclaration with parameters that fail. This narrows the scope to the exact property causing the error—often keywords. Capture the raw request body and compare it to the API’s documentation or sample schema. You want to see if parameters is a valid JSON Schema object that includes “properties”, “type”, and, where appropriate, “required”.

When you inspect functionDeclaration.parameters, check whether the schema is embedded as an object or as a JSON-encoded string. Some MCP wrappers require a JSON object, others expect the schema as a JSON string value (stringified schema). If you get the wrapper expectation wrong, the API will attempt to parse and validate the value and throw INVALID_ARGUMENT. Consult the MCP documentation or the implementation you’re using: mismatch here is common.

Also examine the exact shape of keywords. If you intended keywords to be an array of strings, a robust schema looks like this: set the parameter’s “type”:”array” and set “items”:{“type”:”string”}. If your code produces {“keywords”: null} or {“keywords”:”a,b,c”}, the validator will reject it. The fix requires both adding the proper “type” declaration in the schema and ensuring runtime payloads conform.

Step-by-step fix: define type for keywords and correct the schema

The most reliable fix is twofold: (1) correct the JSON Schema used in functionDeclaration.parameters so every property has an explicit “type”, and (2) ensure the runtime payload matches that schema exactly. Below is a canonical example for a function that accepts a keywords array and an optional filter object. Use this pattern to replace or update the faulty MCP schema.

{
  "name": "searchDocuments",
  "description": "Search documents by keywords and filters",
  "parameters": {
    "type": "object",
    "properties": {
      "keywords": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of search keywords"
      },
      "filters": {
        "type": "object",
        "properties": {
          "language": { "type": "string" },
          "publishedAfter": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      }
    },
    "required": ["keywords"],
    "additionalProperties": false
  }
}

Important notes on the example above: always include “type” at the property level (e.g., “type”: “array” for keywords). Avoid allowing loose typing by setting “additionalProperties”: false where appropriate. If your MCP layer stringifies this schema, make sure it is stringified exactly once (double-stringify is an easy mistake). After you update the schema, update any client-side code to send keywords as an actual array of strings:

{
  "keywords": ["invoice", "2026", "error"],
  "filters": { "language": "en" }
}

If you maintain multiple environments or wrappers, align schema expectations across them. For example, if a gateway expects the schema as JSON text, but the MCP server expects JSON object, create a single transformation function to normalize schema passing to the API.

Validation and testing: tools and approach

Before sending requests to the live Gemini GenAI endpoint, validate your “parameters” JSON Schema with a JSON Schema validator—AJV (Node), jsonschema (Python), or the online JSON Schema Validator. Validation ensures your schema itself is valid and that sample payloads conform to the schema. Feed both the schema and sample payload to the validator to catch type mismatches and format errors.

Include unit tests for schema compatibility. Create a test that instantiates the schema and validates a representative payload (both minimal and maximal variants). Automate these tests in CI so new changes can’t slip in that break the expected type contract. This catches simple regressions like accidentally changing keywords from array to string.

When reproducing errors, enable verbose logging of request bodies and server responses (without logging secrets). The server-side validation stacktrace or error details often contain the exact path of the failing property (e.g., /parameters/properties/keywords/items). Use those paths to pinpoint the issue quickly. If available, consult the MCP or gateway logs where schema parsing and validation occur—those logs often show JSON parsing failures or type assertion exceptions that clarify whether the problem is schema or payload-side.

Preventative best practices

• Always declare explicit types in JSON Schema for every parameter and nested property; never rely on inferred types.
• Ensure consistent serialization: if a wrapper expects stringified JSON Schema, centralize stringification to one place to avoid double-stringify bugs.
• Write schema compatibility tests and include sample payload validations in CI to prevent regressions.

Align documentation, examples, and client libraries. Maintain one canonical schema file in your repo and use it to auto-generate client validation code or TypeScript types. This reduces mismatches between documentation and runtime behavior. Also version your schemas when you change required fields (e.g., making keywords required) so clients can upgrade explicitly.

When you see a new INVALID_ARGUMENT, reproduce it locally against a mock or staging endpoint with the same schema and header configuration. This systematic approach prevents the back-and-forth debugging that often wastes time. And yes, adding a well-labeled assertion that checks keywords is an inexpensive insurance policy.

FAQ

1. Why does the GenAI API return 400 INVALID_ARGUMENT when my JSON looks valid?

The API validates both the JSON syntax and the JSON Schema shape for functionDeclaration.parameters. A syntactically valid JSON may still violate schema constraints (missing “type”, wrong structure, additionalProperties), so the validator refuses the request. Fix the schema and payload to match exactly and validate locally first.

2. Do I need to send the schema as a JSON object or a string?

It depends on your MCP wrapper or gateway. Some wrappers require a JSON object; others accept a stringified JSON Schema. Check your wrapper’s docs and ensure you do not double-stringify. Normalize schema serialization in one place in your codebase to avoid this class of error.

3. How should I define functionDeclaration.parameters.keywords?

Define it explicitly as an array of strings in the parameter schema: use “type”:”array” with “items”:{“type”:”string”}. Make keywords required only if the function cannot operate without them. Validate runtime payloads to ensure keywords is sent as an actual array, not a CSV string or null.

Semantic core (primary, secondary, clarifying keywords)

{
  "primary": [
    "400 INVALID_ARGUMENT error",
    "Google Gemini GenAI API",
    "MCP code schema issue",
    "functionDeclaration.parameters.keywords"
  ],
  "secondary": [
    "schema validation for GenAI API",
    "defining type field for keywords",
    "GenAI API schema fix",
    "parameters.keywords schema",
    "schema mismatch invalid_argument"
  ],
  "clarifying": [
    "JSON Schema keywords array",
    "type: array items: string",
    "AJV validation",
    "payload validation",
    "MCP wrapper schema stringified",
    "how to fix 400 invalid_argument"
  ],
  "lsi_synonyms": [
    "schema validation error",
    "request payload type mismatch",
    "functionDeclaration schema",
    "JSON schema fix for keywords",
    "Gemini API troubleshooting"
  ]
}

Backlinks for further reference: see the MCP sample and fix discussion at MCP code schema fix and Google Gemini GenAI API error.