docs: add MCP tool name troubleshooting

[rothnic]

Summary

• document the common "invalid function name must start with a letter or underscore" error
• explain that MCP tool names starting with numbers (e.g., 1mcp) can trigger it
• suggest renaming the MCP key or disabling the entry when using Antigravity models

Testing

• not run (docs-only change)

[coderabbitai]

Warning

Rate limit exceeded

@rothnic has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 5 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 7d1a79e and 4c702a2.

📒 Files selected for processing (1)

• README.md

Walkthrough

The pull request adds a new "Common symptom" subsection to the README.md file under the MCP Servers Causing Errors section. This subsection documents a specific error condition where MCP function names that start with a number are invalid, provides example error messages that users may encounter, and includes remediation steps: rename the MCP key to begin with a letter or disable the MCP entry for Antigravity models.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add MCP tool name troubleshooting' directly and clearly summarizes the main change: adding documentation for MCP tool name troubleshooting.
Description check	✅ Passed	The description is directly related to the changeset, clearly explaining what documentation was added about MCP tool naming errors and the recommended solutions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

Added troubleshooting documentation for a common MCP tool naming error where function names starting with numbers trigger validation failures in Antigravity models.

• Documented the "Invalid function name must start with a letter or underscore" error
• Explained root cause: MCP tool names starting with numbers (e.g., 1mcp_*)
• Provided clear solution: rename MCP key or disable the entry for Antigravity models
• Included both short and full error message formats for easier recognition

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only change that adds helpful troubleshooting information for a well-understood issue. No code changes, no runtime impact, and the documentation is accurate and well-structured.
• No files require special attention

Important Files Changed

Filename	Overview
README.md	Added troubleshooting documentation for MCP tool name validation errors; clear explanation and actionable solutions provided

Sequence Diagram

sequenceDiagram
    participant User
    participant Antigravity
    participant MCP Server
    participant Gemini API

    User->>Antigravity: Request with MCP tools enabled
    Antigravity->>MCP Server: Fetch tool schemas
    MCP Server-->>Antigravity: Return tool definitions (e.g., 1mcp_*)
    Antigravity->>Antigravity: Validate tool name format
    
    alt Tool name starts with number
        Antigravity->>Gemini API: Send tool with invalid name
        Gemini API-->>Antigravity: Error: Invalid function name
        Antigravity-->>User: Error: must start with letter/underscore
        Note over User: User renames MCP key or disables entry
    else Tool name valid
        Antigravity->>Gemini API: Send properly formatted tools
        Gemini API-->>Antigravity: Success
        Antigravity-->>User: Request completed
    end

Loading

[greptile-apps]

Greptile found no issues!

From now on, if a review finishes and we haven't found any issues, we will not post anything, but you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 356-358: The fenced code block containing the message for
GenerateContentRequest.tools[0].function_declarations[12].name should include a
language specifier to satisfy markdownlint (MD040); update the opening fence
from ``` to something like ```text so the block becomes a labeled code block
(e.g., ```text) and keep the content unchanged.
- Around line 351-353: The fenced code block containing "Invalid function name
must start with a letter or underscore" in README.md lacks a language specifier;
update that fenced block (the triple-backtick block showing that message) to
include a language token such as text (e.g., ```text) so the block renders
correctly and satisfies markdownlint MD040.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 0348742 and 7d1a79e.

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

README.md

351-351: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

356-356: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[rothnic]

This is a quick update to the readme. It seems there are random errors we see here and there with this auth situation being a moving target. This particular issue was one where i setup a new machine and ran across this error that I couldn't find mentioned. So, thought it might help someone debugging to determine that this issue isn't related to auth issues with the api. It is just a limitation for the antigravity api in general.