feat: add MCP tool annotations to all remaining tools

[bryankthompson]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint) to all remaining tools (excluding Looker and MongoDB which already have annotations from #2219).

Changes

• Added Annotations *tools.ToolAnnotations field to Config structs for YAML configuration override
• Added readOnlyHint: true to 92 read-only tools (queries, fetches, lists, gets, searches)
• Added destructiveHint: true to 50 tools that modify data (execute SQL, create, delete, update)
• Used GetAnnotationsOrDefault pattern for user-overridable defaults
• Applied to 156 tool files across all database and service tools

Why This Matters

Tool annotations provide semantic metadata that helps MCP clients:

• Auto-approve safe (read-only) operations without user confirmation
• Show appropriate warnings for destructive operations
• Cache results of read-only tools more aggressively

Classification Approach

• Read-only: Tools that only query/fetch data (list, get, search, schema, stats)
• Destructive: Tools that can modify data (execute SQL, create, update, delete)
• General SQL execution tools marked destructive (can run arbitrary DML)
• Wait/poll and compile/validate tools are read-only

Testing

• go build ./... passes
• go test ./internal/tools/... - all tests pass
• golangci-lint run --fix - 0 issues
• Annotation values match actual tool behavior

CLA Fix

This push resolves the CLA check failure. Commit now authored with correct GitHub noreply email.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @triepod-ai, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the system's compliance with the MCP (Managed Control Plane) specification by integrating standardized tool annotations across a broad spectrum of existing tools. This initiative aims to clearly define the operational characteristics of each tool, distinguishing between read-only and destructive actions, thereby improving overall system governance, security, and the clarity of tool behavior for users and automated systems.

Highlights

• Comprehensive Annotation Coverage: MCP tool annotations have been systematically applied to 137 tools across various database and cloud services, excluding MongoDB tools which are handled in a separate PR.
• Standardized Annotation Logic: Each tool's configuration now includes an Annotations field for user customization. Helper functions (GetAnnotationsOrDefault, NewReadOnlyAnnotations, NewDestructiveAnnotations) are used to provide sensible defaults for read-only or destructive operations, ensuring consistent application of the MCP specification.
• Categorized Tool Behavior: Tools are explicitly categorized as either 'read-only' (e.g., query/fetch operations) or 'destructive' (e.g., execute SQL statements, insert/update/delete operations) based on their functional impact, enhancing operational transparency and safety.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request systematically adds MCP tool annotations to a large number of tools, which is a great enhancement for tool discovery and usage. The implementation follows a consistent and clean pattern, leveraging new helper functions to provide default annotations. However, I've identified two critical issues in cassandracql.go and elasticsearchesql.go where an incorrect variable is used, which will lead to compilation errors. Once these are fixed, this PR will be in excellent shape.

[bryankthompson]

Thanks for catching those compilation errors! Fixed in commit 5289686 - corrected the receiver reference from cfg.Annotations to c.Annotations in both cassandracql.go and elasticsearchesql.go, and added the missing Annotations field to their Config structs.

[duwenxin99]

/gcbrun

[vksinha10]

are we merging this PR?

[duwenxin99]

Hi @bryankthompson, are you still interested in merging this PR? The change LGTM but the test is failing

Already have image (with digest): golang:1
--- Running integration tests for Custom Prompts ---
Error: Test binary not found at ./prompt.custom.test. Aborting.

If so, you may need to rebase and fix the test issues. Thanks!

[bryankthompson]

Thanks for the review feedback! I've merged upstream/main to pick up the latest changes and resolved the conflicts.

The previous test failure (./prompt.custom.test not found) was related to CI infrastructure that my changes don't touch - our tool annotation changes only affect files in internal/tools/.

Let me know if there's anything else I should address!

[duwenxin99]

Hi @bryankthompson the changes LGTM, but we need tests to make sure the annotations are delivered correctly.

[duwenxin99]

LGTM but tests should be added

[bryankthompson]

Hi @duwenxin99 — Added annotation unit tests as requested. Here's what's included:

internal/tools/tools_test.go — 3 new helper function tests:

• TestNewReadOnlyAnnotations — verifies readOnlyHint: true
• TestNewDestructiveAnnotations — verifies destructiveHint: true, readOnlyHint: false
• TestGetAnnotationsOrDefault — nil returns default, non-nil returns custom

95 tool test files — each gets a TestAnnotations() function following the pattern from the MongoDB PR (#2219):

• 24 destructive tools: default destructiveHint == true + readOnlyHint == false, custom override works
• 71 read-only tools: default readOnlyHint == true, custom override works

All tests pass: go test -run TestAnnotations ./internal/tools/... → 196 packages OK, 0 failures.

[bryankthompson]

Hi @duwenxin99 — Rebased on upstream/main and expanded annotation coverage to all remaining tools.

What changed:

• Rebased onto current main (clean single commit, no merge artifacts)
• Added annotations to 47 additional tools that were previously missing (BigQuery, Postgres, Snowflake, CloudLoggingAdmin, CloudSQL backup/restore, CockroachDB, CloudGDA, AlloyDB AI NL)
• CLA signed

Updated totals:

• 285 files changed, 4,069 insertions
• 142 source files: Annotations field + GetAnnotationsOrDefault call
• 143 test files: TestAnnotations() with default + custom override subtests
• 30 destructive + 112 read-only tools annotated
• 213 test packages pass, 0 failures

Every non-Looker, non-MongoDB tool with GetMcpManifest now has annotations and tests.

[duwenxin99]

/gcbrun

[duwenxin99]

Hi @bryankthompson, thanks for the update! Could you please make sure all these contributors account sign the CLA? It is required for any PR to be merged that all contributors sign the CLA. Thanks!

Could you also run golangci-lint run --fix and fix the lint errors? Thank you!

[bryankthompson]

Hi @duwenxin99, thanks for the feedback!

I've addressed both issues:

1. CLA: The previous commit was authored with the wrong email. I've force-pushed with a fresh commit using my GitHub noreply email that has the CLA signed. The PR now has a single commit from bryankthompson.

2. Lint: Ran golangci-lint run --fix - 0 issues.

I also rebased onto the latest main and expanded coverage to include newer tools (dataproc, serverlessspark, cockroachdb, cloudloggingadmin, snowflake, mindsdb, etc.) that were added since my original PR. Total: 156 files annotated (92 read-only, 50 destructive).

[duwenxin99]

/gcbrun