new feat: tool annotation

mcp/tools.go

@@ -75,6 +75,8 @@ type Tool struct {
 	InputSchema ToolInputSchema `json:"inputSchema"`
 	// Alternative to InputSchema - allows arbitrary JSON Schema to be provided
 	RawInputSchema json.RawMessage `json:"-"` // Hide this from JSON marshaling
+	// Optional properties describing tool behavior
+	Annotations ToolAnnotation `json:"annotations"`
 }
 
 // MarshalJSON implements the json.Marshaler interface for Tool.
@@ -109,6 +111,19 @@ type ToolInputSchema struct {
 	Required   []string               `json:"required,omitempty"`
 }
 
+type ToolAnnotation struct {
+	// Human-readable title for the tool
+	Title string `json:"title,omitempty"`
+	// If true, the tool does not modify its environment
+	ReadOnlyHint bool `json:"readOnlyHint,omitempty"`
+	// If true, the tool may perform destructive updates
+	DestructiveHint bool `json:"destructiveHint,omitempty"`
+	// If true, repeated calls with same args have no additional effect
+	IdempotentHint bool `json:"idempotentHint,omitempty"`
+	// If true, tool interacts with external entities
+	OpenWorldHint bool `json:"openWorldHint,omitempty"`
+}
+
 // ToolOption is a function that configures a Tool.
 // It provides a flexible way to set various properties of a Tool using the functional options pattern.
 type ToolOption func(*Tool)
@@ -132,6 +147,13 @@ func NewTool(name string, opts ...ToolOption) Tool {
 			Properties: make(map[string]interface{}),
 			Required:   nil, // Will be omitted from JSON if empty
 		},
+		Annotations: ToolAnnotation{
+			Title:           "",
+			ReadOnlyHint:    false,
+			DestructiveHint: true,
+			IdempotentHint:  false,
+			OpenWorldHint:   true,
+		},
 	}
 
 	for _, opt := range opts {
@@ -166,6 +188,12 @@ func WithDescription(description string) ToolOption {
 	}
 }
 
+func WithToolAnnotation(annotation ToolAnnotation) ToolOption {
+	return func(t *Tool) {
+		t.Annotations = annotation
+	}
+}
+
 //
 // Common Property Options
 //

server/server_test.go

@@ -800,6 +800,13 @@ func TestMCPServer_HandleUndefinedHandlers(t *testing.T) {
 			Type:       "object",
 			Properties: map[string]interface{}{},
 		},
+		Annotations: mcp.ToolAnnotation{
+			Title:           "test-tool",
+			ReadOnlyHint:    true,
+			DestructiveHint: false,
+			IdempotentHint:  false,
+			OpenWorldHint:   false,
+		},
 	}, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		return &mcp.CallToolResult{}, nil
 	})