Validate tool annotations value

Tool annotations were introduced in the "2025-03-26" specification:

> Added comprehensive tool annotations for better describing tool behavior,
> like whether it is read-only or destructive (PR modelcontextprotocol/modelcontextprotocol#185)

https://modelcontextprotocol.io/specification/2025-03-26/changelog#major-changes

This means they are not supported in the "2024-11-05" specification,
so validation errors will be raised for `protocol_version: "2024-11-05"`.

Author: koic

README.md

@@ -448,6 +448,9 @@ Tools can include annotations that provide additional metadata about their behav
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
+> [!NOTE]
+> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
+
 ### Prompts
 
 MCP spec includes [Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.

lib/mcp/server.rb

@@ -59,10 +59,7 @@ def initialize(
       @server_context = server_context
       @configuration = MCP.configuration.merge(configuration)
 
-      if @configuration.protocol_version == "2024-11-05" && @instructions
-        message = "`instructions` supported by protocol version 2025-03-26 or higher"
-        raise ArgumentError, message
-      end
+      validate!
 
       @capabilities = capabilities || default_capabilities
 
@@ -102,6 +99,8 @@ def handle_json(request)
     def define_tool(name: nil, title: nil, description: nil, input_schema: nil, annotations: nil, &block)
       tool = Tool.define(name:, title:, description:, input_schema:, annotations:, &block)
       @tools[tool.name_value] = tool
+
+      validate!
     end
 
     def define_prompt(name: nil, title: nil, description: nil, arguments: [], &block)
@@ -171,6 +170,25 @@ def prompts_get_handler(&block)
 
     private
 
+    def validate!
+      if @configuration.protocol_version == "2024-11-05"
+        if @instructions
+          message = "`instructions` supported by protocol version 2025-03-26 or higher"
+          raise ArgumentError, message
+        end
+
+        error_tool_names = @tools.each_with_object([]) do |(tool_name, tool), error_tool_names|
+          if tool.annotations
+            error_tool_names << tool_name
+          end
+        end
+        unless error_tool_names.empty?
+          message = "Error occurred in #{error_tool_names.join(", ")}. `annotations` are supported by protocol version 2025-03-26 or higher"
+          raise ArgumentError, message
+        end
+      end
+    end
+
     def handle_request(request, method)
       handler = @handlers[method]
       unless handler

test/mcp/server_test.rb

@@ -822,6 +822,28 @@ def call(message:, server_context: nil)
       assert_equal("`instructions` supported by protocol version 2025-03-26 or higher", exception.message)
     end
 
+    test "server uses annotations when configured with protocol version 2025-03-26" do
+      configuration = Configuration.new(protocol_version: "2025-03-26")
+      server = Server.new(name: "test_server", configuration: configuration)
+      server.define_tool(
+        name: "defined_tool",
+        annotations: { title: "test server" },
+      )
+      assert_equal({ destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: false, title: "test server" }, server.tools.first[1].annotations.to_h)
+    end
+
+    test "raises error if annotations are used with protocol version 2024-11-05" do
+      configuration = Configuration.new(protocol_version: "2024-11-05")
+      exception = assert_raises(ArgumentError) do
+        server = Server.new(name: "test_server", configuration: configuration)
+        server.define_tool(
+          name: "defined_tool",
+          annotations: { title: "test server" },
+        )
+      end
+      assert_equal("Error occurred in defined_tool. `annotations` are supported by protocol version 2025-03-26 or higher", exception.message)
+    end
+
     test "#define_tool adds a tool to the server" do
       @server.define_tool(
         name: "defined_tool",