Gemini CLI Invents API Parameters: How to Ground It in Real Schemas

Gemini CLI invents API parameters when it writes or runs a call from patterns in its training data instead of the provider's current schema. The result is a request with a field the API never accepted, a parameter from an older version, or an import from an SDK the provider has deprecated. The fix is to put short rules in GEMINI.md, give the agent a source of truth it can query over MCP, and validate every external call against the real schema before it is sent.

This article covers what invented parameters look like in Gemini CLI, the documented reports, why they happen, what Gemini CLI's configuration can do, and how to connect it to an operation catalog so invalid calls fail closed. Checked against the Gemini CLI documentation and public GitHub issues in October 2026.

What do invented API parameters look like in Gemini CLI?

• Fields the API does not accept. A body or query parameter that sounds right but is missing from the schema, so the provider returns an error or silently ignores it.
• Parameters from another version. Options that existed in an earlier release of the API or SDK and were renamed or removed.
• Deprecated SDKs. Imports from a library the provider has replaced, with the rest of the code written in that library's style.
• Half-finished migrations. The package name gets updated after a correction while the old calling pattern stays in the code.

Documented reports

• Issue #25931 (April 2026). A user on the auto-gemini-3 model reported that Gemini CLI "consistently provides factually incorrect technical documentation, non-existent API parameters, and deprecated library references as if they were current."
• Issue #4618, Google's own SDK. Asked to write a Vertex AI integration in Node.js, Gemini CLI used the deprecated @google/generative-ai package where @google/genai is current. When the user pointed out the new package, it updated package.json and the import but left the rest of the code on the old pattern. The issue was marked a duplicate of tracking issue #4083.

The second case is telling. Google moved its Gemini API libraries to the Google GenAI SDK, which uses a central Client object in place of the older pattern of creating GenerativeModel objects directly, and marked the legacy libraries deprecated. If an agent built on Gemini can reach for the old SDK of its own provider, it can do the same with any API that changed after its training data was collected.

Claude Code, Cursor, Codex, and GitHub Copilot users report the same class of problem. Research on tool calling finds that most wrong calls are well-formed but carry wrong values (ParamBench, arXiv 2608.03071), which is why a format check alone misses them.

Why Gemini CLI invents parameters

• Training data mixes versions. Old and new SDKs, tutorials, and answers all appear in training data, and the older pattern often has more examples.
• Search is optional. Gemini CLI ships with google_web_search and web_fetch, so it can check current docs. Nothing requires it to look before writing a call, and search results can mix versions too.
• The installed version is easy to skip. Unless told to, the agent may choose an SDK without reading package.json or the lockfile.
• Corrections are partial. As issue #4618 shows, fixing the import leaves no guarantee that the calling code is updated to match.
• Nothing validates the call before it runs. An invented field looks the same as a real one until the provider rejects it.

What Gemini CLI configuration can do

A GEMINI.md section for external APIs

Put this in the project's GEMINI.md. Keep it short, name the tools, and say what to do when a call fails. Run /memory show to confirm it loaded.

## External APIs

- Read package.json or the lockfile before choosing an SDK or SDK method.
- Never use an API parameter, field, or endpoint from memory.
- For third-party APIs, use the Swytchcode MCP tools: discover the operation,
  read its schema with info, then exec. Preview writes with dry_run=true.
- If a call fails validation, show the error and stop. Do not switch to an
  older SDK or a different endpoint to make it pass.

How Swytchcode grounds Gemini CLI in real API schemas

Swytchcode is an execution layer between agents and the APIs they call. Gemini CLI describes the job, Swytchcode returns real operations from its catalog, and every call runs through one pipeline: resolve the tool, validate inputs, evaluate policies, resolve credentials, execute, and normalize the response. An invented parameter fails at validation, before any request leaves the machine. Credentials are resolved at execution time and never pass through the model's context.

With the gemini editor option, swy init writes Swytchcode guidance into GEMINI.md and merges a stdio MCP entry into ~/.gemini/settings.json.

# Initialize the project for Gemini CLI in sandbox mode
npm install -g swytchcode
swy init --editor=gemini --mode=sandbox
swy doctor

# The loop Gemini CLI follows for any third-party call
swy discover "add a contact to the CRM" --json
swy get <project>
swy add <canonical_id>
swy info <canonical_id>
swy exec <canonical_id>

The resulting entry is a standard mcpServers block. Leave trust at false so Gemini CLI asks before running tools from the server, and use includeTools to expose only lookups and execution if you prefer a smaller tool set.

// ~/.gemini/settings.json
{
  "mcpServers": {
    "swytchcode": {
      "command": "swytchcode",
      "args": ["mcp", "serve"],
      "trust": false,
      "includeTools": [
        "swytchcode_discover",
        "swytchcode_info",
        "swytchcode_list",
        "swytchcode_exec"
      ]
    }
  }
}

What happens when Gemini CLI guesses anyway:

• Unknown or not-enabled operations are rejected. An invented canonical ID, or a real one that has not been added to the project, exits with code 2 and no request is sent.
• Invented parameters fail validation. A missing required field, a wrong type, or a field the schema does not define exits with code 1 before the provider sees the request.
• Provider errors come back structured. Each error includes the status code, an error category, and whether it is retryable. A 200 response with an error in the body counts as a failure.
• Schema changes are flagged. swy sync compares stored method hashes and warns when an installed operation has changed, which is the moment an API version change would otherwise go unnoticed.
• Writes can be held. dry_run=true previews the request without sending it. For production, allow and deny rules are available from the Pro plan, and approval rules that route a call to Slack or Telegram are available on Business and Enterprise.

Where this does not help

Swytchcode does not choose which SDK your application code imports. If Gemini CLI writes a direct call to a deprecated SDK in your source, code review, type checking, and pinned dependencies catch it. Routing external calls through the Swytchcode runtime SDK (@swytchcode/runtime for JavaScript, swytchcode-runtime for Python) keeps application code tied to canonical IDs and validated inputs instead of a vendor SDK's method names. Swytchcode also cannot tell whether a valid value is the right one for your task, so keep dry runs and approvals on writes.

Frequently asked questions

Why does Gemini CLI use deprecated SDKs?
Older SDKs have more examples in training data. Google's legacy Gemini API libraries are a documented case: Gemini CLI has generated @google/generative-ai code where @google/genai is current. Tell the agent which version is installed and check calls before they run.

Where does Gemini CLI read GEMINI.md from?
From ~/.gemini/GEMINI.md for global rules, then GEMINI.md files in the project and its parent directories, plus files in subdirectories it works in. The contents are combined and sent with every prompt. Run /memory show to see the result.

How do I add an MCP server to Gemini CLI?
Add it under mcpServers in ~/.gemini/settings.json for all projects, or in .gemini/settings.json for one project. Each server needs a command, url, or httpUrl. Run /mcp to check that it connected.

Does Gemini CLI check the docs before writing API code?
It can, using google_web_search and web_fetch, but nothing requires it. A rule in GEMINI.md makes it more likely, and validation at execution time catches what slips through.

Does Swytchcode work with Gemini CLI?
Yes. Run swy init --editor=gemini to add the Swytchcode MCP server to ~/.gemini/settings.json and guidance to GEMINI.md.

Swytchcode resources

• Why AI agents call the wrong API: https://www.swytchcode.com/content/why-your-ai-agent-calls-the-wrong-api-and-how-to-fix-it
• Why Codex calls the wrong API: https://www.swytchcode.com/content/codex-wrong-api-calls
• Why Cursor writes outdated API calls: https://www.swytchcode.com/content/cursor-outdated-api-calls
• GitHub Copilot hallucinated API methods: https://www.swytchcode.com/content/github-copilot-hallucinated-api-methods
• Swytchcode MCP server docs: https://docs.swytchcode.com/cli/mcp/
• CLI command reference: https://docs.swytchcode.com/reference/commands/
• Supported APIs: https://www.swytchcode.com/apis