From 6f5b970824ad2cfcfed0dc4b3936a667eccd5936 Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Fri, 24 Apr 2026 13:06:03 -0300 Subject: [PATCH 1/6] mcp: do not omitempty ReadOnlyHint in ToolAnnotations ReadOnlyHint is a bare bool with omitempty, so the zero value (false) is indistinguishable from unset and drops out of marshaled JSON. Consumers that explicitly set ReadOnlyHint: false on write tools lose the field on the wire. Removing omitempty ensures false is always serialized, which matches the MCP spec default. Co-Authored-By: Claude Opus 4.6 --- mcp/protocol.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/protocol.go b/mcp/protocol.go index 1646788a..39be432f 100644 --- a/mcp/protocol.go +++ b/mcp/protocol.go @@ -1378,7 +1378,7 @@ type ToolAnnotations struct { // If true, the tool does not modify its environment. // // Default: false - ReadOnlyHint bool `json:"readOnlyHint,omitempty"` + ReadOnlyHint bool `json:"readOnlyHint"` // A human-readable title for the tool. Title string `json:"title,omitempty"` } From 7cd2e561ec8cdfb202394b929c6100db85460307 Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Thu, 30 Apr 2026 15:10:09 -0300 Subject: [PATCH 2/6] fix: remove omit empty from IdempotentHint --- mcp/protocol.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mcp/protocol.go b/mcp/protocol.go index 39be432f..c50ea29f 100644 --- a/mcp/protocol.go +++ b/mcp/protocol.go @@ -1368,7 +1368,7 @@ type ToolAnnotations struct { // (This property is meaningful only when ReadOnlyHint == false.) // // Default: false - IdempotentHint bool `json:"idempotentHint,omitempty"` + IdempotentHint bool `json:"idempotentHint"` // If true, this tool may interact with an "open world" of external entities. If // false, the tool's domain of interaction is closed. For example, the world of // a web search tool is open, whereas that of a memory tool is not. From 92701776762cb176393b971585f85aa4d105d7dc Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Thu, 30 Apr 2026 15:15:52 -0300 Subject: [PATCH 3/6] doc: add *bool vs bool case to rough edges --- docs/rough_edges.md | 5 +++++ internal/docs/rough_edges.src.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/rough_edges.md b/docs/rough_edges.md index 7ee18b1a..c1a618df 100644 --- a/docs/rough_edges.md +++ b/docs/rough_edges.md @@ -63,3 +63,8 @@ v2. - `StreamableHTTPOptions.CrossOriginProtection` should not have been part of the SDK API. Cross-origin protection is a general HTTP concern, not specific to MCP, and can be applied as standard HTTP middleware. + +- `ToolAnnotations` (`mcp/protocol.go`) should have all fields typed as `*bool` + for full control to define what is being sent over the wire. Different + MCP clients have different requirements, and some of them require all fields + to be explicitly set to either `true` or `false`. diff --git a/internal/docs/rough_edges.src.md b/internal/docs/rough_edges.src.md index d573e141..90751f74 100644 --- a/internal/docs/rough_edges.src.md +++ b/internal/docs/rough_edges.src.md @@ -62,3 +62,8 @@ v2. - `StreamableHTTPOptions.CrossOriginProtection` should not have been part of the SDK API. Cross-origin protection is a general HTTP concern, not specific to MCP, and can be applied as standard HTTP middleware. + +- `ToolAnnotations` (`mcp/protocol.go`) should have all fields typed as `*bool` + for full control to define what is being sent over the wire. Different + MCP clients have different requirements, and some of them require all fields + to be explicitly set to either `true` or `false`. \ No newline at end of file From f7e4d652fcc5349ac10789bd4bacf4a548157c60 Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Tue, 5 May 2026 14:28:22 -0300 Subject: [PATCH 4/6] doc: mcp debug param for `hintomitempty` --- docs/mcpgodebug.md | 6 ++++++ internal/docs/mcpgodebug.src.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/docs/mcpgodebug.md b/docs/mcpgodebug.md index e5a7d6f5..6ae83cdd 100644 --- a/docs/mcpgodebug.md +++ b/docs/mcpgodebug.md @@ -27,6 +27,12 @@ Options listed below were added and will be removed in the 1.9.0 version of the Params), restoring the previous behavior. The default behavior was changed to align with SEP-2164 and the JSON-RPC specification. +- `hintomitempty` added. If set to `1`, `ToolAnnotations` JSON marshaling + will omit `ReadOnlyHint` and `IdempotentHint` when their value is `false`, + restoring the previous behavior. The default behavior was changed to always + serialize these fields, since their Go types are bare `bool` (not `*bool`) + and omitting `false` made it indistinguishable from unset. + ### 1.6.0 Options listed below were added and will be removed in the 1.8.0 version of the SDK. diff --git a/internal/docs/mcpgodebug.src.md b/internal/docs/mcpgodebug.src.md index c03205b6..37237f5e 100644 --- a/internal/docs/mcpgodebug.src.md +++ b/internal/docs/mcpgodebug.src.md @@ -26,6 +26,12 @@ Options listed below were added and will be removed in the 1.9.0 version of the Params), restoring the previous behavior. The default behavior was changed to align with SEP-2164 and the JSON-RPC specification. +- `hintomitempty` added. If set to `1`, `ToolAnnotations` JSON marshaling + will omit `ReadOnlyHint` and `IdempotentHint` when their value is `false`, + restoring the previous behavior. The default behavior was changed to always + serialize these fields, since their Go types are bare `bool` (not `*bool`) + and omitting `false` made it indistinguishable from unset. + ### 1.6.0 Options listed below were added and will be removed in the 1.8.0 version of the SDK. From 430544bdb884c475a451e468db96738aca957539 Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Tue, 5 May 2026 14:29:58 -0300 Subject: [PATCH 5/6] feat: conditional omitempty --- mcp/protocol.go | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/mcp/protocol.go b/mcp/protocol.go index c50ea29f..fdda198e 100644 --- a/mcp/protocol.go +++ b/mcp/protocol.go @@ -1346,6 +1346,13 @@ type Tool struct { Icons []Icon `json:"icons,omitempty"` } +// hintomitempty is a compatibility parameter that restores the pre-1.7.0 +// behavior of [ToolAnnotations] JSON marshaling, where false-valued bare bool +// fields (ReadOnlyHint, IdempotentHint) were omitted from the output. +// See the documentation for the mcpgodebug package for instructions on how to +// enable it. +var hintomitempty = mcpgodebug.Value("hintomitempty") + // Additional properties describing a Tool to clients. // // NOTE: all properties in ToolAnnotations are hints. They are not @@ -1383,6 +1390,31 @@ type ToolAnnotations struct { Title string `json:"title,omitempty"` } +// MarshalJSON implements [json.Marshaler] for ToolAnnotations. +// +// To restore the previous behavior where false-valued ReadOnlyHint and +// IdempotentHint were omitted, set MCPGODEBUG=hintomitempty=1. +func (t ToolAnnotations) MarshalJSON() ([]byte, error) { + if hintomitempty == "1" { + type compat struct { + DestructiveHint *bool `json:"destructiveHint,omitempty"` + IdempotentHint bool `json:"idempotentHint,omitempty"` + OpenWorldHint *bool `json:"openWorldHint,omitempty"` + ReadOnlyHint bool `json:"readOnlyHint,omitempty"` + Title string `json:"title,omitempty"` + } + return json.Marshal(compat{ + DestructiveHint: t.DestructiveHint, + IdempotentHint: t.IdempotentHint, + OpenWorldHint: t.OpenWorldHint, + ReadOnlyHint: t.ReadOnlyHint, + Title: t.Title, + }) + } + type nomethod ToolAnnotations + return json.Marshal(nomethod(t)) +} + type ToolListChangedParams struct { // This property is reserved by the protocol to allow clients and servers to // attach additional metadata to their responses. From da375a62cc0316507134cd1d5b939e51367e50d5 Mon Sep 17 00:00:00 2001 From: Pavel Bazin Date: Tue, 5 May 2026 14:30:57 -0300 Subject: [PATCH 6/6] tests: omitempty marshaling --- mcp/protocol_test.go | 57 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/mcp/protocol_test.go b/mcp/protocol_test.go index 751d0812..2bab644e 100644 --- a/mcp/protocol_test.go +++ b/mcp/protocol_test.go @@ -1194,3 +1194,60 @@ func TestContentUnmarshal(t *testing.T) { var gotpm PromptMessage roundtrip(pm, &gotpm) } + +func TestToolAnnotations_MarshalJSON(t *testing.T) { + boolPtr := func(b bool) *bool { return &b } + + tests := []struct { + name string + in ToolAnnotations + want string + }{ + { + name: "ZeroValue", + in: ToolAnnotations{}, + want: `{"idempotentHint":false,"readOnlyHint":false}`, + }, + { + name: "AllFalse", + in: ToolAnnotations{ + DestructiveHint: boolPtr(false), + IdempotentHint: false, + OpenWorldHint: boolPtr(false), + ReadOnlyHint: false, + }, + want: `{"destructiveHint":false,"idempotentHint":false,"openWorldHint":false,"readOnlyHint":false}`, + }, + { + name: "AllTrue", + in: ToolAnnotations{ + DestructiveHint: boolPtr(true), + IdempotentHint: true, + OpenWorldHint: boolPtr(true), + ReadOnlyHint: true, + Title: "my tool", + }, + want: `{"destructiveHint":true,"idempotentHint":true,"openWorldHint":true,"readOnlyHint":true,"title":"my tool"}`, + }, + { + name: "MixedValues", + in: ToolAnnotations{ + ReadOnlyHint: true, + Title: "read tool", + }, + want: `{"idempotentHint":false,"readOnlyHint":true,"title":"read tool"}`, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := json.Marshal(tt.in) + if err != nil { + t.Fatalf("json.Marshal(%v) failed: %v", tt.in, err) + } + if diff := cmp.Diff(tt.want, string(got)); diff != "" { + t.Errorf("json.Marshal() mismatch (-want +got):\n%s", diff) + } + }) + } +}