From b4da129aa0fac9ffdd25272af8470f3a42dee610 Mon Sep 17 00:00:00 2001
From: Koichi ITO <koic.ito@gmail.com>
Date: Sat, 23 Aug 2025 00:03:04 +0900
Subject: [PATCH] Document `title` as Draft and restore `annotations.title`

Follow-up to #109.

The introduction of `title` in #109 is still a draft and is not supported in the latest specification, `Version 2025-06-18 (latest)`.

In this PR, the README.md will be updated to mention this point and restore the references to the removed `annotations.title`.

This aims to inform users that, as of `Version 2025-06-18 (latest)`, the use of `annotations.title` is considered stable.

Additionally, separate validation for these parameters could be added.

Please refer to the following comment regarding `annotations.title` and `title`:
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/663#issuecomment-2963519737
---
 README.md             | 20 +++++++++++---------
 test/mcp/tool_test.rb |  3 ++-
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index fbb2af2e..312f06b1 100644
--- a/README.md
+++ b/README.md
@@ -373,7 +373,7 @@ This gem provides a `MCP::Tool` class that can be used to create tools in two wa
 
 ```ruby
 class MyTool < MCP::Tool
-  title "My Tool"
+  title "My Tool" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This tool performs specific functionality..."
   input_schema(
     properties: {
@@ -385,7 +385,8 @@ class MyTool < MCP::Tool
     read_only_hint: true,
     destructive_hint: false,
     idempotent_hint: true,
-    open_world_hint: false
+    open_world_hint: false,
+    title: "My Tool"
   )
 
   def self.call(message:, server_context:)
@@ -401,10 +402,11 @@ tool = MyTool
 ```ruby
 tool = MCP::Tool.define(
   name: "my_tool",
-  title: "My Tool",
+  title: "My Tool", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description: "This tool performs specific functionality...",
   annotations: {
-    read_only_hint: true
+    read_only_hint: true,
+    title: "My Tool"
   }
 ) do |args, server_context|
   MCP::Tool::Response.new([{ type: "text", text: "OK" }])
@@ -418,11 +420,11 @@ e.g. around authentication state.
 
 Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
 
-- `title`: A human-readable title for the tool
-- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
 - `destructive_hint`: Indicates if the tool performs destructive operations
 - `idempotent_hint`: Indicates if the tool's operations are idempotent
 - `open_world_hint`: Indicates if the tool operates in an open world context
+- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state)
+- `title`: A human-readable title for the tool
 
 Annotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.
 
@@ -437,7 +439,7 @@ The `MCP::Prompt` class provides two ways to create prompts:
 ```ruby
 class MyPrompt < MCP::Prompt
   prompt_name "my_prompt"  # Optional - defaults to underscored class name
-  title "My Prompt"
+  title "My Prompt" # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description "This prompt performs specific functionality..."
   arguments [
     MCP::Prompt::Argument.new(
@@ -474,7 +476,7 @@ prompt = MyPrompt
 ```ruby
 prompt = MCP::Prompt.define(
   name: "my_prompt",
-  title: "My Prompt",
+  title: "My Prompt", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description: "This prompt performs specific functionality...",
   arguments: [
     MCP::Prompt::Argument.new(
@@ -561,7 +563,7 @@ The `MCP::Resource` class provides a way to register resources with the server.
 resource = MCP::Resource.new(
   uri: "https://example.com/my_resource",
   name: "my-resource",
-  title: "My Resource",
+  title: "My Resource", # WARNING: This is a `Draft` and is not supported in the `Version 2025-06-18 (latest)` specification.
   description: "Lorem ipsum dolor sit amet",
   mime_type: "text/html",
 )
diff --git a/test/mcp/tool_test.rb b/test/mcp/tool_test.rb
index f4b16dbf..3fda6ccd 100644
--- a/test/mcp/tool_test.rb
+++ b/test/mcp/tool_test.rb
@@ -133,6 +133,7 @@ class InputSchemaTool < Tool
         description: "a mock tool for testing",
         annotations: {
           read_only_hint: true,
+          title: "Mock Tool",
         },
       ) do |_|
         Tool::Response.new([{ type: "text", content: "OK" }])
@@ -142,7 +143,7 @@ class InputSchemaTool < Tool
       assert_equal tool.title, "Mock Tool"
       assert_equal tool.description, "a mock tool for testing"
       assert_equal tool.input_schema, Tool::InputSchema.new
-      assert_equal tool.annotations_value.to_h, { readOnlyHint: true }
+      assert_equal tool.annotations_value.to_h, { readOnlyHint: true, title: "Mock Tool" }
     end
 
     # Tests for Tool::Annotations class