fix(google): validate tool names to prevent API errors

[codewarnab]

Background

The Gemini API enforces strict validation on tool (function) names. Currently, the SDK passes invalid tool names (e.g., those starting with numbers) directly to the API, resulting in a 400 error. This error can be confusing and hard to debug for users.
api error can be verified with this

Summary

I added client-side validation in prepareTools to check if tool names match Gemini's requirements (regex: ^[a-zA-Z_][a-zA-Z0-9_.:-]*$).
If a name is invalid, the SDK now throws a descriptive Error immediately, instead of making a failing API call.

Design Decision: Validation vs. Sanitization

I considered automatically sanitizing tool names (e.g., prefixing with fn_ or removing invalid characters) to make them valid. However, I decided against this for the following reasons:

1. Complexity: Automatic mapping requires maintaining a consistent map between the original name and the sanitized name to ensure model responses (which use the sanitized name) can be correctly mapped back to the original tool. This adds significant complexity to the SDK.
2. Debugging Confusion: If the SDK silently changes tool names, users inspecting network traffic will see tool names they didn't define. This implicit behavior can lead to confusion when debugging.
3. Explicit is better than implicit: Throwing an error forces the developer to fix the issue at the source, ensuring their code is correct and explicit.

But I am open to feedback if maintainers prefer a sanitization approach.

Manual Verification

I created a reproduction test case in google-prepare-tools.test.ts that defines a tool named 123invalid.

• Before the fix: The test would fail (or rather, the API would fail in a real scenario).
• After the fix: The test passes by catching the expected "Invalid tool name" error.

I verified this by running pnpm test:node src/google-prepare-tools.test.ts in packages/google.

Checklist

• Tests have been added / updated
• Documentation has been added / updated
• A patch changeset for relevant packages has been added
• I have reviewed this pull request (self-review)

[Copilot]

Pull request overview

This PR adds client-side validation for Google Gemini tool names to prevent API errors. The validation ensures tool names conform to Gemini's naming requirements (must start with a letter or underscore, followed by alphanumeric characters, underscores, dots, colons, or dashes) before making API calls, providing clearer error messages to developers.

Changes:

• Added regex validation for tool names in prepareTools function
• Added test case to verify invalid tool names are rejected with appropriate error

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/google/src/google-prepare-tools.ts	Added validation logic to check tool names against Gemini API requirements; includes formatting adjustments to type definitions
packages/google/src/google-prepare-tools.test.ts	Added test case to verify error is thrown for invalid tool names starting with numbers

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.