Expose MCP tool annotations (readOnlyHint, destructiveHint) in PreToolCallDecideHook

[jiridanek]

Environment

• google-antigravity SDK v0.1.3
• Python 3.14
• macOS

Problem

The MCP protocol defines ToolAnnotations on tool definitions (spec):

class ToolAnnotations:
    title: str | None
    readOnlyHint: bool | None        # Tool doesn't modify state
    destructiveHint: bool | None     # Tool may perform destructive updates
    idempotentHint: bool | None      # Repeated calls with same args have no additional effect
    openWorldHint: bool | None       # Tool interacts with external entities

MCP servers can annotate their tools with these hints. Hosts are starting to use them for various purposes:

• Claude Code uses readOnlyHint as a concurrency hint — true enables parallel execution of MCP tools, false or missing forces serialization (docs)
• Goose classifies tools as low-risk (read) vs high-risk (write/destructive) for its SmartApprove mode — currently heuristic-based, but could be annotation-driven

The Antigravity SDK does not expose these annotations. When an MCP tool call arrives at PreToolCallDecideHook, the ToolCall object only has name, args, and id — no way to access the tool's declared annotations.

Evidence

The SDK's MCP tool handling in local_connection.py only extracts server_name, tool_name, and arguments_json from the proto — annotations are not read or forwarded:

if not found_action and step_update.HasField(_MCP_TOOL_PROTO_FIELD):
    mcp_pb = getattr(step_update, _MCP_TOOL_PROTO_FIELD)
    action_str = _get_mcp_tool_name(mcp_pb.server_name, mcp_pb.tool_name)
    found_action = True
    args = json.loads(mcp_pb.arguments_json or "{}")

No annotation-related fields exist anywhere in the SDK:

$ grep -r "readOnlyHint\|destructiveHint\|idempotentHint\|openWorldHint\|ToolAnnotation" \
    .venv/lib/python3.14/site-packages/google/antigravity/
# (no results)

Use case

I'm building an ACP adapter that wraps the Antigravity SDK for JetBrains IDEs. The PreToolCallDecideHook gates tool calls — safe tools auto-allow, while dangerous tools prompt the user for approval in the IDE UI.

Currently I maintain a hardcoded whitelist of safe tool names (view_file, list_directory, etc.), but for MCP server tools (prefixed mcp_*) I have no way to distinguish list_pages (read-only) from execute_tool (destructive). All MCP tools require manual approval, which is slow and annoying for read-only operations.

If annotations were exposed on ToolCall (or accessible via the agent/hook context), I could auto-approve readOnlyHint=True tools from trusted servers and only prompt for others — rather than reimplementing heuristic classification or hardcoding tool names.

Proposed API

Add an annotations field to ToolCall (or a lookup method on the hook context):

# Option A: on ToolCall directly
@dataclasses.dataclass
class ToolCall:
    name: str
    args: dict
    id: str | None
    annotations: ToolAnnotations | None = None  # NEW

# Option B: on HookContext
class HookContext:
    def get_tool_annotations(self, tool_name: str) -> ToolAnnotations | None: ...

This requires the Go harness to forward annotations from the MCP server's tools/list response through the proto to the Python SDK.

Workaround

The only current option is to hardcode tool names or require user approval for all MCP tools. Neither scales across arbitrary MCP servers.

References

• MCP spec — Tool annotations
• Claude Code — uses readOnlyHint for parallel tool execution
• Related: McpStdioServer missing env field — proto supports it but Python model doesn't expose it #61 (McpStdioServer missing env field — another MCP feature gap)
• Related: Add include_tools / exclude_tools to McpServerConfig (parity with Gemini CLI includeTools) #28 (include_tools/exclude_tools — MCP tool filtering)

[NTaylorMullen]

To be extra clear you're effectively looking for tool schema to be surfaced as part of tool context right?

[Rul1an]

Yes, but I’d frame it as the effective MCP tool metadata rather than only the input schema.

For a PreToolCallDecideHook, the useful surface is the annotations observed for the selected server/tool from tools/list: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. I’d keep them nullable so omitted stays different from explicit false.

That lets a host policy say: auto-allow read-only tools from trusted MCP servers, prompt on destructive or undeclared tools, and fall back to heuristics when the server did not declare anything.

One boundary worth keeping in docs/tests: these hints are server declarations, not proof. readOnlyHint=True is useful policy input only after the host has already decided it trusts that MCP server. It would also help to expose the original MCP server/tool identity beside the flattened mcp_<server>_<tool> name, so hooks can make that trust decision cleanly. That is the same split we use downstream in Assay-style audit checks: declarations help explain the decision, but they are never the decision by themselves.

[Fon199800]

ในวันที่ อา. 14 มิ.ย. 2026 10:50 น. Rul1an ***@***.***> เขียนว่า:

…

*Rul1an* left a comment (google-antigravity/antigravity-sdk-python#62) <#62 (comment)> Yes, but I’d frame it as the effective MCP tool metadata rather than only the input schema. For a PreToolCallDecideHook, the useful surface is the annotations observed for the selected server/tool from tools/list: readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. I’d keep them nullable so omitted stays different from explicit false. That lets a host policy say: auto-allow read-only tools from trusted MCP servers, prompt on destructive or undeclared tools, and fall back to heuristics when the server did not declare anything. One boundary worth keeping in docs/tests: these hints are server declarations, not proof. readOnlyHint=True is useful policy input only after the host has already decided it trusts that MCP server. It would also help to expose the original MCP server/tool identity beside the flattened mcp_<server>_<tool> name, so hooks can make that trust decision cleanly. That is the same split we use downstream in Assay-style audit checks: declarations help explain the decision, but they are never the decision by themselves. — Reply to this email directly, view it on GitHub <#62?email_source=notifications&email_token=BNRBY7DIOIW6BSPDNXXWTV347YOIZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINZQGA3DCNRSGEYKM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4700616210>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNRBY7HCOH4KVU6CXAMGL7347YOIZAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMRVGAYDKNBWGM5US43TOVSTWNBWGU3DSMJVGEZDFILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BNRBY7BEIJZ3GQADKZP57G347YOIZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINZQGA3DCNRSGEYKM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android <https://github.com/notifications/mobile/android/BNRBY7BQ6ZVIHLEMUUEYKHD47YOIZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINZQGA3DCNRSGEYKM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.*** .com>