Add tool annotations support (yjacquin#96)

* Add tool annotations support

* use snake case for annotation keys

* fix linter

Author: parruda

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Tool annotations support for providing hints about tool behavior (readOnlyHint, destructiveHint, etc.)
+
 ## [1.5.0] - 2025-06-01
 ### Added
 - Handle filtering tools and resources [#85 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/85)

docs/tools.md

@@ -13,6 +13,7 @@ Tools are a core concept in the Model Context Protocol (MCP). They allow you to
   - [Default Values](#default-values)
 - [Calling Tools From Another Tool](#calling-tools-from-another-tool)
 - [Advanced Tool Features](#advanced-tool-features)
+  - [Tool Annotations](#tool-annotations)
   - [Tool Hidden Arguments](#tool-hidden-arguments)
   - [Tool Categories](#tool-categories)
   - [Tool Metadata](#tool-metadata)
@@ -277,6 +278,67 @@ end
 
 ## Advanced Tool Features
 
+### Tool Annotations
+
+Tool annotations provide additional metadata about a tool's behavior, helping clients understand how to present and manage tools. These annotations are hints that describe the nature and impact of a tool.
+
+```ruby
+class WebSearchTool < FastMcp::Tool
+  description 'Search the web for information'
+  
+  annotations(
+    title: 'Web Search',           # Human-readable title for the tool
+    read_only_hint: true,          # Indicates the tool doesn't modify its environment
+    open_world_hint: true          # The tool interacts with external entities
+  )
+  
+  arguments do
+    required(:query).filled(:string).description('Search query')
+  end
+  
+  def call(query:)
+    "Searching for: #{query}"
+  end
+end
+```
+
+Available annotations:
+
+| Annotation | Type | Default | Description |
+|------------|------|---------|-------------|
+| `title` | string | - | A human-readable title for the tool, useful for UI display |
+| `read_only_hint` | boolean | false | If true, indicates the tool does not modify its environment |
+| `destructive_hint` | boolean | true | If true, the tool may perform destructive updates (only meaningful when `read_only_hint` is false) |
+| `idempotent_hint` | boolean | false | If true, calling the tool repeatedly with the same arguments has no additional effect |
+| `open_world_hint` | boolean | true | If true, the tool may interact with an "open world" of external entities |
+
+Example with all annotations:
+
+```ruby
+class DeleteFileTool < FastMcp::Tool
+  description 'Delete a file from the filesystem'
+  
+  annotations(
+    title: 'Delete File',
+    read_only_hint: false,     # This tool modifies the filesystem
+    destructive_hint: true,    # Deleting files is destructive
+    idempotent_hint: true,     # Deleting the same file twice has no additional effect
+    open_world_hint: false     # Only interacts with the local filesystem
+  )
+  
+  arguments do
+    required(:path).filled(:string).description('File path to delete')
+  end
+  
+  def call(path:)
+    File.delete(path) if File.exist?(path)
+    "File deleted: #{path}"
+  end
+end
+```
+
+**Important**: Annotations are hints and not guaranteed to provide a faithful description of tool behavior. Clients should never make security-critical decisions based solely on annotations.
+
 ### Tool hidden arguments
 If need be, we can register arguments that won't show up in the tools/list call but can still be used in the tool when provided.
 This might be useful when calling from another tool, or when the client is made aware of this argument from the context.

examples/tool_examples.rb

@@ -201,3 +201,88 @@ def call(args)
   email: 'jane@example.com',
   age: 25
 )}"
+puts
+
+# Example 7: Tools with annotations
+puts 'Example 7: Tools with annotations'
+
+class WebSearchTool < FastMcp::Tool
+  description 'Search the web for information'
+
+  annotations(
+    title: 'Web Search',
+    read_only_hint: true,
+    open_world_hint: true
+  )
+
+  arguments do
+    required(:query).filled(:string).description('Search query')
+    optional(:max_results).filled(:integer, gteq?: 1, lteq?: 50).description('Maximum number of results')
+  end
+
+  def call(args)
+    max_results = args[:max_results] || 10
+    "Searching for '#{args[:query]}' (returning up to #{max_results} results)..."
+  end
+end
+
+class DeleteFileTool < FastMcp::Tool
+  description 'Delete a file from the filesystem'
+
+  annotations(
+    title: 'Delete File',
+    read_only_hint: false,
+    destructive_hint: true,
+    idempotent_hint: true,
+    open_world_hint: false
+  )
+
+  arguments do
+    required(:path).filled(:string).description('File path to delete')
+  end
+
+  def call(args)
+    "Would delete file at: #{args[:path]}"
+  end
+end
+
+class CreateRecordTool < FastMcp::Tool
+  description 'Create a new record in the database'
+
+  annotations(
+    title: 'Create Database Record',
+    read_only_hint: false,
+    destructive_hint: false,
+    idempotent_hint: false,
+    open_world_hint: false
+  )
+
+  arguments do
+    required(:table).filled(:string).description('Database table name')
+    required(:data).hash.description('Record data')
+  end
+
+  def call(args)
+    "Creating record in #{args[:table]} with data: #{args[:data].inspect}"
+  end
+end
+
+# Demonstrate the web search tool
+web_search = WebSearchTool.new
+puts "Tool: #{web_search.class.name}"
+puts "Annotations: #{web_search.class.annotations.inspect}"
+puts "Call result: #{web_search.call(query: 'Ruby programming')}"
+puts
+
+# Demonstrate the delete file tool
+delete_file = DeleteFileTool.new
+puts "Tool: #{delete_file.class.name}"
+puts "Annotations: #{delete_file.class.annotations.inspect}"
+puts "Call result: #{delete_file.call(path: '/tmp/test.txt')}"
+puts
+
+# Demonstrate the create record tool
+create_record = CreateRecordTool.new
+puts "Tool: #{create_record.class.name}"
+puts "Annotations: #{create_record.class.annotations.inspect}"
+puts "Call result: #{create_record.call(table: 'users', data: { name: 'John', email: 'john@example.com' })}"

lib/generators/fast_mcp/install/templates/sample_tool.rb

@@ -3,6 +3,13 @@
 class SampleTool < ApplicationTool
   description 'Greet a user'
 
+  # Optional: Add annotations to provide hints about the tool's behavior
+  # annotations(
+  #   title: 'User Greeting',
+  #   read_only_hint: true,      # This tool only reads data
+  #   open_world_hint: false     # This tool only accesses the local database
+  # )
+
   arguments do
     required(:id).filled(:integer).description('ID of the user to greet')
     optional(:prefix).filled(:string).description('Prefix to add to the greeting')

lib/mcp/server.rb

@@ -294,11 +294,25 @@ def handle_initialized_notification
     # Handle tools/list request
     def handle_tools_list(id)
       tools_list = @tools.values.map do |tool|
-        {
+        tool_info = {
           name: tool.tool_name,
           description: tool.description || '',
           inputSchema: tool.input_schema_to_json || { type: 'object', properties: {}, required: [] }
         }
+
+        # Add annotations if they exist
+        annotations = tool.annotations
+        unless annotations.empty?
+          # Convert snake_case keys to camelCase for MCP protocol
+          camel_case_annotations = {}
+          annotations.each do |key, value|
+            camel_key = key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }.to_sym
+            camel_case_annotations[camel_key] = value
+          end
+          tool_info[:annotations] = camel_case_annotations
+        end
+
+        tool_info
       end
 
       send_result({ tools: tools_list }, id)

lib/mcp/tool.rb

@@ -138,6 +138,12 @@ def description(description = nil)
         @description = description
       end
 
+      def annotations(annotations_hash = nil)
+        return @annotations || {} if annotations_hash.nil?
+
+        @annotations = annotations_hash
+      end
+
       def authorize(&block)
         @authorization_blocks ||= []
         @authorization_blocks.push block

spec/mcp/server_spec.rb

@@ -156,6 +156,66 @@ def call(user:)
 
         server.handle_request(request)
       end
+      
+      context 'with tool annotations' do
+        let(:annotated_tool_class) do
+          Class.new(FastMcp::Tool) do
+            def self.name
+              'annotated-tool'
+            end
+
+            def self.description
+              'A tool with annotations'
+            end
+            
+            annotations(
+              title: 'Web Search Tool',
+              read_only_hint: true,
+              open_world_hint: true
+            )
+
+            def call(**_args)
+              'Searching...'
+            end
+          end
+        end
+        
+        before do
+          server.register_tool(annotated_tool_class)
+        end
+        
+        it 'includes annotations in the tools list' do
+          request = { jsonrpc: '2.0', method: 'tools/list', id: 1 }.to_json
+
+          expect(server).to receive(:send_result) do |result, id|
+            expect(id).to eq(1)
+            
+            annotated_tool = result[:tools].find { |t| t[:name] == 'annotated-tool' }
+            expect(annotated_tool[:annotations]).to eq({
+              title: 'Web Search Tool',
+              readOnlyHint: true,
+              openWorldHint: true
+            })
+          end
+
+          server.handle_request(request)
+        end
+      end
+      
+      context 'with tool without annotations' do
+        it 'does not include annotations field' do
+          request = { jsonrpc: '2.0', method: 'tools/list', id: 1 }.to_json
+
+          expect(server).to receive(:send_result) do |result, id|
+            expect(id).to eq(1)
+            
+            test_tool = result[:tools].find { |t| t[:name] == 'test-tool' }
+            expect(test_tool).not_to have_key(:annotations)
+          end
+
+          server.handle_request(request)
+        end
+      end
     end
 
     context 'with a tools/call request' do

spec/mcp/tool_spec.rb

@@ -643,4 +643,46 @@ def call(**_args)
       expect(test_class.metadata(:undefined_key)).to be_nil
     end
   end
+
+  describe '.annotations' do
+    it 'sets and returns annotations hash' do
+      test_class = Class.new(described_class)
+      annotations = {
+        title: 'Web Search',
+        read_only_hint: true,
+        open_world_hint: true
+      }
+      test_class.annotations(annotations)
+      
+      expect(test_class.annotations).to eq(annotations)
+    end
+    
+    it 'returns empty hash when no annotations are set' do
+      test_class = Class.new(described_class)
+      
+      expect(test_class.annotations).to eq({})
+    end
+    
+    it 'returns the current annotations when called with nil' do
+      test_class = Class.new(described_class)
+      annotations = { title: 'Test Tool' }
+      test_class.annotations(annotations)
+      
+      expect(test_class.annotations(nil)).to eq(annotations)
+    end
+    
+    it 'supports all MCP annotation fields' do
+      test_class = Class.new(described_class)
+      annotations = {
+        title: 'Delete File',
+        read_only_hint: false,
+        destructive_hint: true,
+        idempotent_hint: true,
+        open_world_hint: false
+      }
+      test_class.annotations(annotations)
+      
+      expect(test_class.annotations).to eq(annotations)
+    end
+  end
 end