Add tool annotation hint fields (readOnlyHint, destructiveHint, etc.) to Annotations

[ssathy2]

The MCP::Annotations class currently supports audience, priority, and last_modified, but the MCP spec also defines several hint fields for tools that clients like Claude use to make safety decisions (e.g. requiring confirmation before calling a destructive tool):

• title — human-readable title for the tool
• readOnlyHint — whether the tool only reads data without modifying state
• destructiveHint — whether the tool may modify or destroy data
• idempotentHint — whether the tool is safe to retry
• openWorldHint — whether the tool interacts with the outside world

We ran into this while adding annotations to our MCP server for the Claude MCP Directory submission. Our workaround is prepending a module onto MCP::Annotations to add the missing fields:

module McpAnnotationsHints
  attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint

  def initialize(title: nil, read_only_hint: nil, destructive_hint: nil,
    idempotent_hint: nil, open_world_hint: nil, **rest)
    super(**rest)
    @title = title
    @read_only_hint = read_only_hint
    @destructive_hint = destructive_hint
    @idempotent_hint = idempotent_hint
    @open_world_hint = open_world_hint
  end

  def to_h
    super.merge(
      title: title,
      readOnlyHint: read_only_hint,
      destructiveHint: destructive_hint,
      idempotentHint: idempotent_hint,
      openWorldHint: open_world_hint
    ).compact
  end
end

MCP::Annotations.prepend(McpAnnotationsHints)

This works fine but would be nice to have natively in the gem. Happy to put up a PR if that'd be helpful!

[koic]

The requested fields are already available in MCP::Tool::Annotations (not MCP::Annotations).

There are two separate annotations classes in the SDK:

• MCP::Annotations ... metadata for content (audience, priority, lastModified)
• MCP::Tool::Annotations ... capability hints for tools (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint)

The tool annotations are documented in the https://github.com/modelcontextprotocol/ruby-sdk#tools with usage examples for all three tool definition styles (class definition, Tool.define, and Server#define_tool). There is also a dedicated https://github.com/modelcontextprotocol/ruby-sdk#tool-annotations describing each field.

Closing as already implemented.