feat(policy): Propagate Tool Annotations for MCP Servers

[jerop]

Fixes #19654
Followup on #20029

• Add annotations property to ToolBuilder and DeclarativeTool base classes to store semantic metadata.
• Update DiscoveredMCPTool to preserve and propagate annotations captured during MCP discovery.
• Propagate tool metadata to the Policy Engine during execution via checkPolicy.
• Migrate hardcoded Plan Mode read-only logic to declarative rules in plan.toml, maintaining ask_user behavior for MCP tools.
• Add unit and integration tests for metadata propagation and standard MCP behavioral hints.

[gemini-code-assist]

Summary of Changes

Hello @jerop, 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 policy engine's capabilities by introducing a mechanism to propagate semantic metadata (annotations) from tools to the policy evaluation process. This change allows for more granular and declarative policy enforcement, moving away from hardcoded logic, particularly for Plan Mode. By enabling tools to declare their characteristics and behaviors, the system can make more intelligent and customizable decisions about tool execution, improving both security and flexibility.

Highlights

• Tool Metadata Propagation: Introduced an annotations property to ToolBuilder and DeclarativeTool base classes to store semantic metadata, enabling tools to carry behavioral hints.
• Policy Engine Integration: Updated DiscoveredMCPTool to preserve and propagate annotations captured during MCP discovery, ensuring this metadata is passed to the Policy Engine during execution via checkPolicy.
• Declarative Plan Mode Policies: Migrated hardcoded Plan Mode read-only logic to declarative rules within plan.toml, allowing for more flexible and customizable policy enforcement based on tool annotations, while maintaining ask_user behavior for MCP tools.
• Documentation Updates: Added new documentation and examples for customizing Plan Mode policies using toolAnnotations, specifically demonstrating how to automatically approve read-only MCP tools.
• Testing: Included comprehensive unit and integration tests to validate the metadata propagation pipeline and the new standard MCP behavioral hints within the policy engine.

Changelog

• docs/cli/plan-mode.md
  • Updated documentation to reflect that Plan Mode policies are defined in plan.toml.
  • Added a new example demonstrating how to automatically approve read-only MCP tools using toolAnnotations in custom policies.
• docs/reference/policy-engine.md
  • Documented the new toolAnnotations field for policy rules, explaining its use for semantic matching based on tool metadata.
  • Added an example illustrating how to allow all read-only MCP tools using toolAnnotations.
• packages/cli/src/config/policy-engine.integration.test.ts
  • Added integration tests to verify that read-only MCP tools are correctly handled by the declarative plan.toml policy in Plan Mode.
  • Expanded integration tests for toolAnnotations to cover various annotation combinations and their impact on policy decisions.
• packages/core/src/policy/policies/plan.toml
  • Added a new policy rule to plan.toml that sets the decision to ask_user for all MCP tools with readOnlyHint = true in Plan Mode.
• packages/core/src/policy/policy-engine.ts
  • Modified debug logging to include the modes property when a policy rule matches, providing more context for debugging.
• packages/core/src/scheduler/policy.test.ts
  • Added a test case to ensure that tool annotations are correctly passed from the checkPolicy function to the policy engine.
• packages/core/src/scheduler/policy.ts
  • Updated the checkPolicy function to include toolCall.tool.annotations when calling the policy engine's check method.
• packages/core/src/telemetry/loggers.test.ts
  • Adjusted a test call to logToolCall to accommodate the newly added annotations parameter.
• packages/core/src/tools/mcp-client.test.ts
  • Removed the dynamic addition of policy rules for read-only MCP tools, as this is now handled declaratively in plan.toml.
  • Updated tests to verify that DiscoveredMCPTool correctly captures and stores all annotations during discovery.
  • Removed unused imports related to ApprovalMode and PolicyDecision.
• packages/core/src/tools/mcp-client.ts
  • Removed the logic responsible for dynamically adding policy rules for read-only MCP tools.
  • Modified the discoverTools function to pass the full toolDef.annotations object to the DiscoveredMCPTool constructor.
  • Removed unused imports related to ApprovalMode and PolicyDecision.
• packages/core/src/tools/mcp-tool.test.ts
  • Added new test cases to confirm that DiscoveredMCPTool correctly stores and retrieves the annotations property.
  • Updated existing DiscoveredMCPTool constructor calls to include the new annotations parameter.
• packages/core/src/tools/mcp-tool.ts
  • Modified the DiscoveredMCPTool constructor to accept and store an optional annotations object.
  • Updated constructor calls within DiscoveredMCPTool to pass annotations to its base class.
  • Adjusted import statements for various types to use type keyword where appropriate.
• packages/core/src/tools/tools.ts
  • Added an optional annotations property to the ToolBuilder interface and DeclarativeTool abstract class.

Activity

• No specific activity (comments, reviews, etc.) was provided in the context.

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 introduces a metadata propagation pipeline for tools by adding an annotations property. This allows for more declarative policy rules, as demonstrated by migrating the hardcoded Plan Mode logic for read-only MCP tools to a plan.toml configuration file. The changes are well-supported by updated documentation and new integration tests. I've found one high-severity issue related to the handling of empty toolAnnotations in policy rules, which could cause them to not match as expected.

[github-actions]

Size Change: +2.46 kB (+0.01%)

Total Size: 25.7 MB

Filename	Size	Change
./bundle/gemini.js	25.3 MB	+2.46 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[Abhijit-2592]

LGTM! Approved!