feat: Add tool annotations to MongoDB tools for improved LLM understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint) to all 9 MongoDB tools to help LLMs better understand tool behavior and make safer decisions.

Changes

Tool	Annotation
mongodb-find	readOnlyHint: true
mongodb-find-one	readOnlyHint: true
mongodb-aggregate	readOnlyHint: true
mongodb-insert-one	destructiveHint: true
mongodb-insert-many	destructiveHint: true
mongodb-update-one	destructiveHint: true
mongodb-update-many	destructiveHint: true
mongodb-delete-one	destructiveHint: true
mongodb-delete-many	destructiveHint: true

Implementation

Each tool now:

1. Has an Annotations field in its Config struct for YAML configurability
2. Provides default annotations if not explicitly configured
3. Passes annotations to GetMcpManifest() instead of nil

This follows the exact pattern established by the Looker tools (e.g., lookergetconnectionschemas, lookerupdateprojectfile).

Why This Matters

• Semantic metadata: Annotations provide information beyond just the tool description
• Safety signals: readOnlyHint tells LLMs a tool is safe to call without side effects
• Destructive awareness: destructiveHint signals LLMs should be more careful before executing
• Better tool selection: LLMs can prioritize read-only tools for information gathering
• MCP compliance: Follows the MCP tool annotations specification

Testing

• CI builds successfully
• tools/list returns annotations in MCP response

Files Changed

• internal/tools/mongodb/mongodbfind/mongodbfind.go
• internal/tools/mongodb/mongodbfindone/mongodbfindone.go
• internal/tools/mongodb/mongodbaggregate/mongodbaggregate.go
• internal/tools/mongodb/mongodbinsertone/mongodbinsertone.go
• internal/tools/mongodb/mongodbinsertmany/mongodbinsertmany.go
• internal/tools/mongodb/mongodbupdateone/mongodbupdateone.go
• internal/tools/mongodb/mongodbupdatemany/mongodbupdatemany.go
• internal/tools/mongodb/mongodbdeleteone/mongodbdeleteone.go
• internal/tools/mongodb/mongodbdeletemany/mongodbdeletemany.go

🤖 Generated with Claude Code

[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 integrates Model Context Protocol (MCP) tool annotations into the MongoDB toolset. By adding readOnlyHint and destructiveHint metadata, the changes provide Large Language Models (LLMs) with a deeper semantic understanding of each tool's operational impact. This enhancement is crucial for improving LLM safety, enabling better tool selection, and ensuring compliance with the MCP specification, ultimately leading to more reliable and context-aware automated interactions with MongoDB.

Highlights

• MCP Tool Annotations Added: Model Context Protocol (MCP) tool annotations, specifically readOnlyHint and destructiveHint, have been integrated into all nine MongoDB tools.
• Enhanced LLM Understanding: These annotations provide Large Language Models (LLMs) with crucial semantic metadata about each tool's behavior, enabling safer and more informed decision-making during tool selection and execution.
• Configurability and Defaults: Each MongoDB tool's Config struct now includes an Annotations field for YAML-based configuration. Default annotations are automatically applied (e.g., readOnlyHint: true for read operations, destructiveHint: true for write/delete operations) if not explicitly set.
• Integration with MCP Manifest: The annotations are now passed to the GetMcpManifest() function, ensuring compliance with the MCP specification and consistent metadata exposure.
• Pattern Alignment: This implementation follows the established pattern for tool annotations seen in other integrations, such as the Looker tools.

🧠 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 consistently adds readOnlyHint and destructiveHint annotations to all 9 MongoDB tools, which is a valuable enhancement for LLM interaction. The implementation correctly adds a new Annotations field to each tool's Config struct and provides appropriate default values. The changes are well-aligned with the PR's goal. My main feedback is regarding the code duplication for setting the default annotations, which is repeated across all modified files. I've left a comment with a suggestion to refactor this into centralized helper functions to improve long-term maintainability. Overall, this is a good feature addition.

[gemini-code-assist]

This logic for setting default annotations is duplicated across the 9 MongoDB tool files in this pull request. While the implementation is correct, and I see from the PR description that this follows an existing pattern, this repetition could pose a maintenance challenge in the future. For instance, adding a new default annotation would require changes in all 9 locations.

To improve maintainability and adhere to the DRY (Don't Repeat Yourself) principle, consider centralizing this logic. A potential approach is to introduce helper functions in the tools package.

For example, you could have:

// In internal/tools/tools.go

// NewReadOnlyAnnotations creates default annotations for a read-only tool.
func NewReadOnlyAnnotations() *ToolAnnotations {
    readOnly := true
    return &ToolAnnotations{ReadOnlyHint: &readOnly}
}

// NewDestructiveAnnotations creates default annotations for a destructive tool.
func NewDestructiveAnnotations() *ToolAnnotations {
    readOnly := false
    destructive := true
    return &ToolAnnotations{
        ReadOnlyHint:    &readOnly,
        DestructiveHint: &destructive,
    }
}

With these helpers, this block could be simplified to:

// Add default annotations
annotations := cfg.Annotations
if annotations == nil {
    annotations = tools.NewReadOnlyAnnotations()
}

This would apply similarly to the destructive tools using tools.NewDestructiveAnnotations().

Since this refactoring would affect files outside this PR, it could be addressed in a follow-up change to improve the overall codebase health.

[triepod-ai]

Thanks for the excellent feedback! I've addressed the code duplication concern by adding centralized helper functions to tools.go:

• NewReadOnlyAnnotations() - creates default annotations for read-only tools
• NewDestructiveAnnotations() - creates default annotations for destructive tools
• GetAnnotationsOrDefault() - returns config annotations if set, otherwise applies defaults

All MongoDB tools have been refactored to use these helpers, reducing the per-tool annotation logic from ~8 lines to a single line:

annotations := tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations)

This centralizes the defaults and will make adding annotations to the remaining ~140 tools much cleaner. Net result: -39 lines of code while adding the helper infrastructure.

[duwenxin99]

Hi @triepod-ai, thanks for adding this feature! The implementation looks good to me. Could you include tests and documentation for this? An Mcp annotation test can be added similar to the prompt test. You can add the annotation docs here as a new section. Thanks!

[triepod-ai]

Hi @duwenxin99,

Thanks for the review feedback! I've addressed the requested changes:

Tests Added:

• Added TestAnnotations function to all 9 MongoDB tool test files
• Tests verify default annotations are correctly applied:
  • Read-only tools (find, findone, aggregate): readOnlyHint: true
  • Destructive tools (insert*, update*, delete*): destructiveHint: true, readOnlyHint: false
• Tests verify custom YAML annotations override the defaults

Documentation Added:

• Added "Tool Annotations" section to docs/en/resources/tools/_index.md
• Documents all 4 annotation types: readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• Shows YAML configuration examples and MCP response format

All tests pass locally. Ready for re-review!

[duwenxin99]

/gcbrun

[duwenxin99]

why are we using t.Error instead of t.Fatal here?