odata_duty 0.30.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24b2763892ae6cc0088ab89de9281a39c0ecf100406950f6263e8a364bdd2abc
-  data.tar.gz: 185bee55b726314b02f5add982464b0b949189a592fcff7a1ba9f6b33939b2b7
+  metadata.gz: c58f2ad8e1d2a92312d71682cab83159e525dcd5ff2e774b64ccb1c2b91bdef2
+  data.tar.gz: d368f2c3fdbe2ea07508df7087290831694c281b2e22e07243a00393f43bfd52
 SHA512:
-  metadata.gz: b3490f5fb35ca308175a3c08e3bc0fdcbc822b80334b1642ff073c02281e0d54d60b78a8c9155efac8c713ca1b3b4e66fb67ac99233497bd542620369e25b446
-  data.tar.gz: 92f65ccdb8c6efb24fcea1f39af2e16651f7b4e937e7304998f56e26cccdcf2c19a7d36d84013b314f53f2bf6689d78958b3c144e3a1233aed781a5ae3f45501
+  metadata.gz: 5b288c003fc87adca34c4eb48f389c00d60dc69f0b4de8ec1c88b2046c7259f2c8f0f7168ce954a6ec021767b9cdc150fdfe7559d269ee54eeb61a3659be551b
+  data.tar.gz: 925162bd086fd4a22ccbff521380c67375387c2ae0f6aea954978d21d5d215cdec9b4c0ea3bec6cbdc3c3fbed0f8c17a045f345ef9ccab293bf6441f0c6a201e

data/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-16
+
+### Added
+- `description:` keyword/macro on every schema element — schema, entity/complex/enum type,
+  enum member, property (including `property_ref`), and entity set — in both the class-based
+  and builder DSLs. Descriptions render into `$metadata` (`Core.Description` annotations),
+  `$oas2` (`info`, definitions, properties, operation `summary`/`description`), and MCP
+  (tool descriptions, input-schema property descriptions, server `instructions`) (#63).
+- Build-time MCP identifier validation: `to_mcp_server` now raises
+  `OdataDuty::InvalidMcpIdentifierError` before returning a server if a generated tool name
+  or input-schema property key would violate the Anthropic Messages API's identifier
+  constraints — non-ASCII or oversized property names, oversized entity-set-derived tool
+  names, or a property colliding with a reserved `odata_*` key (#62).
+
+### Changed
+- **Breaking (MCP tool shape):** the MCP tools' OData query-option arguments are renamed
+  from `$filter`, `$select`, `$search`, `$top`, and `$skip` to `odata_filter`,
+  `odata_select`, `odata_search`, `odata_top`, and `odata_skip`. `$`-prefixed keys violate
+  the Anthropic Messages API's tool-schema identifier pattern and previously broke
+  `tools/list` for any Claude-based MCP client. The OData HTTP endpoints are unaffected —
+  they still use the standard `$`-prefixed query options (#62).
+
+### Documentation
+- New `doc/using_descriptions.md`; `doc/using_mcp.md` and `doc/using_oas2.md` updated for
+  descriptions and the new MCP argument names.
+
 ## [0.30.1] - 2026-08-02
 
 ### Added
@@ -58,7 +84,8 @@ All notable changes to this project are documented here. The format is based on
 See the [git tags](https://github.com/NEXL-LTS/odata_duty-ruby/tags) for the history of
 releases prior to 0.21.0.
 
-[Unreleased]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.30.1...HEAD
+[Unreleased]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.31.0...HEAD
+[0.31.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.30.1...v0.31.0
 [0.30.1]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.30.0...v0.30.1
 [0.30.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.21.4...v0.30.0
 [0.21.4]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.21.3...v0.21.4

data/README.md

@@ -74,8 +74,9 @@ See the [Entity Set Generator documentation](doc/entity_set_generator.md) for mo
 require 'odata_duty'
 
 class PersonEntity < OdataDuty::EntityType
+  description 'People present at the event'
   property_ref 'id', String
-  property 'user_name', String, nullable: false
+  property 'user_name', String, nullable: false, description: 'Unique login handle'
   property 'name', String
   property 'emails', [String], nullable: false
 end
@@ -249,6 +250,7 @@ end
 - [Using `$search`](doc/using_search.md)
 - [Using `create`, `update`, and `delete`](doc/using_create_update_and_delete.md)
 - [Using `computed` (read-only) properties](doc/using_computed.md)
+- [Using `description`](doc/using_descriptions.md)
 - [Using `$oas2` (OpenAPI/Swagger) with Power Automate](doc/using_oas2.md)
 
 > **Documentation convention:** Every externally-facing feature (a new DSL option,
@@ -262,7 +264,6 @@ end
 ## TODO
 
 - Add support for composite keys
-- Add support for schema descriptions
 - Extend protocol adapters (MCP tools, resource reading)
 
 ---

data/lib/metadata.xml.erb

@@ -10,20 +10,34 @@
         <Schema Namespace="<%= metadata.namespace %>" xmlns="http://docs.oasis-open.org/odata/ns/edm">
              <% if metadata.version %><Annotation Term="<%= metadata.namespace %>.Version" String="<%= metadata.version %>" /><% end %>
              <% if metadata.title %><Annotation Term="<%= metadata.namespace %>.Title" String="<%= metadata.title %>" /><% end %>
+             <% if metadata.description %><Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(metadata.description) %>" /><% end %>
 
              <% metadata.enum_types.each do |enum_type| %>
                 <EnumType Name="<%= enum_type.name %>">
+                    <% if enum_type.description %>
+                        <Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(enum_type.description) %>" />
+                    <% end %>
                     <% enum_type.members.each do |member| %>
-                        <Member Name="<%= member.name %>" />
+                        <% if member.description %>
+                            <Member Name="<%= member.name %>">
+                                <Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(member.description) %>" />
+                            </Member>
+                        <% else %>
+                            <Member Name="<%= member.name %>" />
+                        <% end %>
                     <% end %>
                 </EnumType>
             <% end %>
             <% metadata.complex_types.each do |complex_type| %>
                 <ComplexType Name="<%= complex_type.name %>">
+                    <% if complex_type.description %>
+                        <Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(complex_type.description) %>" />
+                    <% end %>
                     <% complex_type.properties.each do |property| %>
-                        <% if property.core_annotation_term %>
+                        <% if property.description || property.core_annotation_term %>
                             <Property Name="<%= property.name %>" Nullable="<%= property.nullable %>" Type="<%= property.collection? ? "Collection(" : "" %><%= property.type.include?(".") ? "" : "#{metadata.namespace}." %><%= property.type %><%= property.collection? ? ")" : "" %>">
-                                <Annotation Term="<%= property.core_annotation_term %>" Bool="true" />
+                                <% if property.description %><Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(property.description) %>" /><% end %>
+                                <% if property.core_annotation_term %><Annotation Term="<%= property.core_annotation_term %>" Bool="true" /><% end %>
                             </Property>
                         <% else %>
                             <Property Name="<%= property.name %>" Nullable="<%= property.nullable %>" Type="<%= property.collection? ? "Collection(" : "" %><%= property.type.include?(".") ? "" : "#{metadata.namespace}." %><%= property.type %><%= property.collection? ? ")" : "" %>" />
@@ -33,15 +47,19 @@
             <% end %>
             <% metadata.entity_types.each do |entity_type| %>
                 <EntityType Name="<%= entity_type.name %>">
+                    <% if entity_type.description %>
+                        <Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(entity_type.description) %>" />
+                    <% end %>
                     <Key>
                         <% entity_type.property_refs.each do |property| %>
                             <PropertyRef Name="<%= property.name %>" />
                         <% end %>
                     </Key>
                     <% entity_type.properties.each do |property| %>
-                        <% if property.core_annotation_term %>
+                        <% if property.description || property.core_annotation_term %>
                             <Property Name="<%= property.name %>" Nullable="<%= property.nullable %>" Type="<%= property.collection? ? "Collection(" : "" %><%= property.type.include?(".") ? "" : "#{metadata.namespace}." %><%= property.type %><%= property.collection? ? ")" : "" %>">
-                                <Annotation Term="<%= property.core_annotation_term %>" Bool="true" />
+                                <% if property.description %><Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(property.description) %>" /><% end %>
+                                <% if property.core_annotation_term %><Annotation Term="<%= property.core_annotation_term %>" Bool="true" /><% end %>
                             </Property>
                         <% else %>
                             <Property Name="<%= property.name %>" Nullable="<%= property.nullable %>" Type="<%= property.collection? ? "Collection(" : "" %><%= property.type.include?(".") ? "" : "#{metadata.namespace}." %><%= property.type %><%= property.collection? ? ")" : "" %>" />
@@ -52,6 +70,9 @@
             <EntityContainer Name="Container">
                 <% metadata.entity_sets.each do |entity_set| %>
                     <EntitySet Name="<%= entity_set.name %>" EntityType="<%= metadata.namespace %>.<%= entity_set.entity_type_name %>">
+                        <% if entity_set.description %>
+                            <Annotation Term="Org.OData.Core.V1.Description" String="<%= escape_xml(entity_set.description) %>" />
+                        <% end %>
                         <% if entity_set.supports_search? %>
                             <Annotation Term="Capabilities.SearchRestrictions">
                                 <Record>

data/lib/odata_duty/complex_type.rb

@@ -2,6 +2,11 @@ require_relative 'mapper_builder'
 
 module OdataDuty
   class ComplexType
+    def self.description(text = nil)
+      @description = Property.resolve_description(__metadata.name, text) unless text.nil?
+      @description
+    end
+
     def self.properties
       @properties ||= []
     end
@@ -35,6 +40,10 @@ module OdataDuty
         name
       end
 
+      def description
+        complex_type.description
+      end
+
       def metadata_type
         :complex
       end

data/lib/odata_duty/edmx_schema.rb

@@ -15,5 +15,11 @@ module OdataDuty
       b = binding
       ERB.new(File.read("#{__dir__}/../metadata.xml.erb")).result(b)
     end
+
+    ESCAPE_XML_ENTITIES = { '&' => '&amp;', '"' => '&quot;', '<' => '&lt;' }.freeze
+
+    def self.escape_xml(string)
+      string.gsub(/[&"<]/, ESCAPE_XML_ENTITIES)
+    end
   end
 end

data/lib/odata_duty/enum_type.rb

@@ -1,19 +1,25 @@
 module OdataDuty
   class EnumMember
-    attr_reader :name
+    attr_reader :name, :description
 
-    def initialize(name)
+    def initialize(name, description: nil)
       @name = name.to_str
+      @description = Property.resolve_description(@name, description)
     end
   end
 
   class EnumType
+    def self.description(text = nil)
+      @description = Property.resolve_description(__metadata.name, text) unless text.nil?
+      @description
+    end
+
     def self.members
       @members ||= []
     end
 
-    def self.member(name)
-      members << EnumMember.new(name)
+    def self.member(name, **)
+      members << EnumMember.new(name, **)
     end
 
     class Metadata
@@ -27,6 +33,10 @@ module OdataDuty
         enum_type.members
       end
 
+      def description
+        enum_type.description
+      end
+
       def scalar?
         true
       end

data/lib/odata_duty/errors.rb

@@ -3,7 +3,9 @@ module OdataDuty
 
   class PropertyAlreadyDefinedError < ArgumentError; end
   class InvalidNCNamesError < ArgumentError; end
+  class InvalidMcpIdentifierError < ArgumentError; end
   class InitArgsMismatchError < ArgumentError; end
+  class InvalidDescriptionError < ArgumentError; end
 
   class RequestError < Error
     attr_reader :code, :target

data/lib/odata_duty/mcp_identifier_validator.rb

@@ -0,0 +1,30 @@
+module OdataDuty
+  # Guards `McpServerBuilder`'s generated tool names and `input_schema` property keys against the
+  # Anthropic Messages API's tool-schema identifier constraints, before a tool is registered on
+  # the MCP server. Raises `InvalidMcpIdentifierError` on the first violation found.
+  module McpIdentifierValidator
+    extend self
+
+    # Property keys additionally allow `.`.
+    PROPERTY_KEY_REGEXP = /\A[a-zA-Z0-9_.-]{1,64}\z/
+    TOOL_NAME_REGEXP = /\A[a-zA-Z0-9_-]{1,64}\z/
+
+    def validate_tool_name!(name)
+      return if name.match?(TOOL_NAME_REGEXP)
+
+      raise InvalidMcpIdentifierError,
+            "tool name \"#{name}\" is #{name.length} characters — MCP tool names must " \
+            "match #{TOOL_NAME_REGEXP.inspect}"
+    end
+
+    def validate_properties!(endpoint, tool_name, input_schema)
+      input_schema.fetch('properties').each_key do |key|
+        next if key.match?(PROPERTY_KEY_REGEXP)
+
+        raise InvalidMcpIdentifierError,
+              "#{endpoint.entity_type.name} property \"#{key}\" cannot be used as an MCP tool " \
+              "input key — it must match #{PROPERTY_KEY_REGEXP.inspect} (#{tool_name})"
+      end
+    end
+  end
+end

data/lib/odata_duty/mcp_input_schemas.rb

@@ -5,27 +5,51 @@ module OdataDuty
     # Property names are used as-is (symbols) for keys/required and the root `type: object` is
     # omitted; the MCP SDK normalizes the keys and supplies the root type default.
 
+    # `$`-prefixed OData system query options are not valid Anthropic tool-schema property keys
+    # (`^[a-zA-Z0-9_.-]{1,64}$`), so tool schemas expose these `odata_*` aliases instead.
+    # McpServerBuilder uses the same mapping (inverted) to translate `tools/call` arguments back.
+    QUERY_OPTION_ALIASES = {
+      '$filter' => 'odata_filter',
+      '$select' => 'odata_select',
+      '$search' => 'odata_search',
+      '$top' => 'odata_top',
+      '$skip' => 'odata_skip'
+    }.freeze
+
     def count_input_schema(supports_search:)
-      properties = { '$filter' => { 'type' => 'string' } }
-      properties['$search'] = { 'type' => 'string' } if supports_search
+      properties = { alias_for('$filter') => { 'type' => 'string' } }
+      properties[alias_for('$search')] = { 'type' => 'string' } if supports_search
       { 'properties' => properties, 'required' => [] }
     end
 
     def list_input_schema(supports_search:)
       properties = {
-        '$filter' => { 'type' => 'string', 'description' => 'OData $filter expression' },
-        '$select' => { 'type' => 'string',
-                       'description' => 'Comma-separated properties to return' }
+        alias_for('$filter') => query_option('string', 'OData $filter expression'),
+        alias_for('$select') => query_option('string', 'Comma-separated properties to return')
       }
       if supports_search
-        properties['$search'] = { 'type' => 'string',
-                                  'description' => 'Search expression (AND, OR, NOT)' }
+        properties[alias_for('$search')] = query_option('string',
+                                                        'Search expression (AND, OR, NOT)')
       end
-      properties['$top'] = { 'type' => 'integer', 'description' => 'Max records to return' }
-      properties['$skip'] = { 'type' => 'integer', 'description' => 'Records to skip' }
+      properties[alias_for('$top')] = query_option('integer', 'Max records to return')
+      properties[alias_for('$skip')] = query_option('integer', 'Records to skip')
       { 'properties' => properties, 'required' => [] }
     end
 
+    # Raises when an entity property is literally named like a reserved `odata_*` alias and
+    # would silently overwrite (or be overwritten by) the reserved query-option key in the same
+    # `properties` hash — see McpServerBuilder's tool-name/property-key validation.
+    def add_alias!(properties, entity_type, query_option_key, value, tool_name:)
+      key = alias_for(query_option_key)
+      if properties.keys.map(&:to_s).include?(key)
+        raise InvalidMcpIdentifierError,
+              "#{entity_type.name} property \"#{key}\" collides with the reserved #{key} " \
+              "query-option key in the #{tool_name} tool input schema"
+      end
+
+      properties[key] = value
+    end
+
     def create_input_schema(entity_type)
       writable = entity_type.properties.select(&:settable_on_create?)
       properties = writable.to_h { |p| [p.name, p.to_oas2] }
@@ -41,13 +65,11 @@ module OdataDuty
       { 'properties' => properties, 'required' => [key.name] }
     end
 
-    def get_input_schema(entity_type)
+    def get_input_schema(entity_type, tool_name:)
       key = entity_type.property_refs.first
-      properties = {
-        key.name => key.to_oas2,
-        '$select' => { 'type' => 'string',
-                       'description' => 'Comma-separated properties to return' }
-      }
+      properties = { key.name => key.to_oas2 }
+      select_value = query_option('string', 'Comma-separated properties to return')
+      add_alias!(properties, entity_type, '$select', select_value, tool_name: tool_name)
       { 'properties' => properties, 'required' => [key.name] }
     end
 
@@ -55,5 +77,13 @@ module OdataDuty
       key = entity_type.property_refs.first
       { 'properties' => { key.name => key.to_oas2 }, 'required' => [key.name] }
     end
+
+    def alias_for(query_option_key)
+      QUERY_OPTION_ALIASES.fetch(query_option_key)
+    end
+
+    def query_option(type, description)
+      { 'type' => type, 'description' => description }
+    end
   end
 end

data/lib/odata_duty/mcp_server_builder.rb

@@ -1,14 +1,24 @@
 require 'mcp'
 require 'odata_duty/mcp_input_schemas'
+require 'odata_duty/mcp_identifier_validator'
+require 'odata_duty/operation_verbs'
 
 module OdataDuty
   module McpServerBuilder
     extend self
 
+    # Inverse of McpInputSchemas::QUERY_OPTION_ALIASES: translates a tool call's `odata_*`
+    # arguments back to their `$`-prefixed OData spelling before they reach Executor.
+    QUERY_OPTION_SPELLINGS = McpInputSchemas::QUERY_OPTION_ALIASES.invert.freeze
+
     def build(schema)
       server = MCP::Server.new(
         name: schema.title,
         version: schema.version,
+        # Relies on the `mcp` gem's `initialize` response builder `.compact`-ing away a nil
+        # `instructions:`, so a schema without a description omits the key rather than sending
+        # `"instructions": null` — worth re-checking on `mcp` gem upgrades.
+        instructions: schema.description,
         capabilities: { tools: {} }
       )
       schema.endpoints.each { |endpoint| register_endpoint_tools(server, schema, endpoint) }
@@ -29,51 +39,61 @@ module OdataDuty
     end
 
     def register_update_tool(server, schema, endpoint)
-      register_key_tool(server, schema, endpoint, :update, 'Update an existing')
+      register_key_tool(server, schema, endpoint, :update)
     end
 
     def register_delete_tool(server, schema, endpoint)
-      register_key_tool(server, schema, endpoint, :delete, 'Delete an existing')
+      register_key_tool(server, schema, endpoint, :delete)
     end
 
     def register_list_tool(server, schema, endpoint)
       input_schema = McpInputSchemas.list_input_schema(supports_search: endpoint.supports_search?)
-      define_tool(server, schema, :execute,
-                  url_for: ->(_args) { endpoint.url },
-                  name: "list_#{endpoint.name}",
-                  description: "List #{endpoint.name} records", input_schema: input_schema)
+      description = tool_description(OperationVerbs.list(endpoint.name), endpoint)
+      tool_args = { name: "list_#{endpoint.name}", description: description,
+                    input_schema: input_schema }
+      define_tool(server, schema, :execute, url_for: ->(_args) { endpoint.url }, **tool_args)
     end
 
     def register_count_tool(server, schema, endpoint)
       input_schema = McpInputSchemas.count_input_schema(supports_search: endpoint.supports_search?)
+      description = tool_description(OperationVerbs.count(endpoint.name), endpoint)
+      tool_args = { name: "count_#{endpoint.name}", description: description,
+                    input_schema: input_schema }
       define_tool(server, schema, :execute,
-                  url_for: ->(_args) { "#{endpoint.url}/$count" },
-                  name: "count_#{endpoint.name}",
-                  description: "Count #{endpoint.name} records", input_schema: input_schema)
+                  url_for: ->(_args) { "#{endpoint.url}/$count" }, **tool_args)
     end
 
     def register_create_tool(server, schema, endpoint)
-      define_tool(server, schema, :create,
-                  url_for: ->(_args) { endpoint.url },
-                  name: "create_#{endpoint.name}",
-                  description: "Create a new #{endpoint.name} record",
-                  input_schema: McpInputSchemas.create_input_schema(endpoint.entity_type))
+      tool_name = "create_#{endpoint.name}"
+      input_schema = McpInputSchemas.create_input_schema(endpoint.entity_type)
+      description = tool_description(OperationVerbs.create(endpoint.name), endpoint)
+      tool_args = { name: tool_name, description: description, input_schema: input_schema }
+      McpIdentifierValidator.validate_properties!(endpoint, tool_name, input_schema)
+      define_tool(server, schema, :create, url_for: ->(_args) { endpoint.url }, **tool_args)
     end
 
     def register_get_tool(server, schema, endpoint)
-      define_tool(server, schema, :execute,
-                  url_for: keyed_url_for(endpoint),
-                  name: "get_#{endpoint.name}",
-                  description: "Get a single #{endpoint.name} record by ID",
-                  input_schema: McpInputSchemas.get_input_schema(endpoint.entity_type))
+      tool_name = "get_#{endpoint.name}"
+      input_schema = McpInputSchemas.get_input_schema(endpoint.entity_type, tool_name: tool_name)
+      description = tool_description(OperationVerbs.get(endpoint.name), endpoint)
+      tool_args = { name: tool_name, description: description, input_schema: input_schema }
+      McpIdentifierValidator.validate_properties!(endpoint, tool_name, input_schema)
+      define_tool(server, schema, :execute, url_for: keyed_url_for(endpoint), **tool_args)
     end
 
-    def register_key_tool(server, schema, endpoint, action, verb)
+    def register_key_tool(server, schema, endpoint, action)
+      tool_name = "#{action}_#{endpoint.name}"
       input_schema = McpInputSchemas.public_send("#{action}_input_schema", endpoint.entity_type)
-      define_tool(server, schema, action,
-                  url_for: keyed_url_for(endpoint),
-                  name: "#{action}_#{endpoint.name}",
-                  description: "#{verb} #{endpoint.name} record", input_schema: input_schema)
+      description = tool_description(OperationVerbs.public_send(action, endpoint.name), endpoint)
+      tool_args = { name: tool_name, description: description, input_schema: input_schema }
+      McpIdentifierValidator.validate_properties!(endpoint, tool_name, input_schema)
+      define_tool(server, schema, action, url_for: keyed_url_for(endpoint), **tool_args)
+    end
+
+    def tool_description(verb_text, endpoint)
+      return verb_text unless endpoint.description
+
+      "#{verb_text}. #{endpoint.description}"
     end
 
     # Builds the `<url>('<key>')` locator from the tool arguments. The dynamic `args[key]` lookup
@@ -87,13 +107,24 @@ module OdataDuty
     # On the .mutant.yml ignore list: `server_context[:context]` has only equivalent mutants
     # (`[]` vs `fetch`/`dig`); the key is always present, so no public-API test distinguishes them.
     def define_tool(server, schema, action, url_for:, **tool_args)
+      McpIdentifierValidator.validate_tool_name!(tool_args[:name])
       server.define_tool(**tool_args) do |server_context:, **args|
         McpServerBuilder.run_tool(action, url: url_for.call(args), schema: schema,
                                           context: server_context[:context],
-                                          query_options: args.transform_keys(&:to_s))
+                                          query_options: McpServerBuilder.query_options_for(action,
+                                                                                            args))
       end
     end
 
+    # The `odata_*` aliases only stand in for OData query options on read (`:execute`) tools —
+    # `:create`/`:update`/`:delete` tools' arguments are property values, so a property literally
+    # named e.g. `odata_select` must reach Executor unchanged, not get aliased to `$select`.
+    def query_options_for(action, args)
+      return args.transform_keys(&:to_s) unless action == :execute
+
+      args.to_h { |key, value| [QUERY_OPTION_SPELLINGS.fetch(key.to_s, key.to_s), value] }
+    end
+
     # On the .mutant.yml ignore list: `e.message` has only an equivalent mutant (`e`), since an
     # OdataDuty::Error renders identically to its message in the text content block.
     def run_tool(action, url:, schema:, context:, query_options:)

data/lib/odata_duty/oas2/collection_get_path.rb

@@ -75,11 +75,19 @@ module OdataDuty
             instance.respond_to?(PARAMETER_REQUIREMENTS[param['name']])
         end
         {
-          'operationId' => "GetCollectionOf#{entity_set.name}",
+          'operationId' => "GetCollectionOf#{entity_set.name}"
+        }.merge(summary_and_description).merge(
           'produces' => ['application/json'],
           'parameters' => parameters,
           'responses' => { '200' => oas2_success_response, 'default' => DEFAULT_ERROR_RESPONSE }
-        }
+        )
+      end
+
+      def summary_and_description
+        return {} unless entity_set.description
+
+        { 'summary' => OperationVerbs.list(entity_set.name),
+          'description' => entity_set.description }
       end
 
       def oas2_success_response

data/lib/odata_duty/oas2/collection_post_path.rb

@@ -4,11 +4,12 @@ module OdataDuty
       def self.to_oas2(entity_set)
         path_info = new(entity_set)
         {
-          'operationId' => path_info.operation_id,
+          'operationId' => path_info.operation_id
+        }.merge(path_info.summary_and_description).merge(
           'produces' => path_info.produces,
           'parameters' => path_info.parameters,
           'responses' => path_info.responses
-        }
+        )
       end
 
       def self.request_body_definition(entity_set)
@@ -28,6 +29,13 @@ module OdataDuty
         "Create#{@entity_set.name}"
       end
 
+      def summary_and_description
+        return {} unless @entity_set.description
+
+        { 'summary' => OperationVerbs.create(@entity_set.name),
+          'description' => @entity_set.description }
+      end
+
       def produces
         ['application/json']
       end

data/lib/odata_duty/oas2/individual_delete_path.rb

@@ -4,10 +4,11 @@ module OdataDuty
       def self.to_oas2(entity_set)
         path_info = new(entity_set)
         {
-          'operationId' => path_info.operation_id,
+          'operationId' => path_info.operation_id
+        }.merge(path_info.summary_and_description).merge(
           'parameters' => path_info.parameters,
           'responses' => path_info.responses
-        }
+        )
       end
 
       def initialize(entity_set)
@@ -18,6 +19,13 @@ module OdataDuty
         "Delete#{@entity_set.name}"
       end
 
+      def summary_and_description
+        return {} unless @entity_set.description
+
+        { 'summary' => OperationVerbs.delete(@entity_set.name),
+          'description' => @entity_set.description }
+      end
+
       def parameters
         [
           { 'name' => 'id', 'in' => 'path', 'required' => true, 'type' => id_type }

data/lib/odata_duty/oas2/individual_get_path.rb

@@ -3,11 +3,18 @@ module OdataDuty
     class IndividualGetPath < SimpleDelegator
       def to_oas2
         {
-          'operationId' => "GetIndividual#{name}ById",
+          'operationId' => "GetIndividual#{name}ById"
+        }.merge(summary_and_description).merge(
           'produces' => ['application/json'],
           'parameters' => oas2_parameters,
           'responses' => oas2_responses
-        }
+        )
+      end
+
+      def summary_and_description
+        return {} unless description
+
+        { 'summary' => OperationVerbs.get(name), 'description' => description }
       end
 
       def oas2_parameters

data/lib/odata_duty/oas2/individual_patch_path.rb

@@ -4,11 +4,12 @@ module OdataDuty
       def self.to_oas2(entity_set)
         path_info = new(entity_set)
         {
-          'operationId' => path_info.operation_id,
+          'operationId' => path_info.operation_id
+        }.merge(path_info.summary_and_description).merge(
           'produces' => path_info.produces,
           'parameters' => path_info.parameters,
           'responses' => path_info.responses
-        }
+        )
       end
 
       def self.request_body_definition(entity_set)
@@ -26,6 +27,13 @@ module OdataDuty
         "Update#{@entity_set.name}"
       end
 
+      def summary_and_description
+        return {} unless @entity_set.description
+
+        { 'summary' => OperationVerbs.update(@entity_set.name),
+          'description' => @entity_set.description }
+      end
+
       def produces
         ['application/json']
       end

data/lib/odata_duty/oas2.rb

@@ -1,5 +1,6 @@
 require_relative 'context_wrapper'
 require_relative 'schema_builder/endpoint'
+require_relative 'operation_verbs'
 
 module OdataDuty
   class OAS2
@@ -27,6 +28,7 @@ module OdataDuty
                 'paths' => paths, 'definitions' => definitions }
       info['version'] = schema.version if schema.version
       info['title'] = schema.title if schema.title
+      info['description'] = schema.description if schema.description
     end
 
     ERROR_PROPERTIES = {

data/lib/odata_duty/operation_verbs.rb

@@ -0,0 +1,14 @@
+module OdataDuty
+  # Generated verb text shared between MCP tool descriptions (McpServerBuilder) and the `$oas2`
+  # operation `summary` (oas2/*_path.rb), keyed by operation, so the two contracts can't drift.
+  module OperationVerbs
+    extend self
+
+    def list(name) = "List #{name} records"
+    def count(name) = "Count #{name} records"
+    def create(name) = "Create a new #{name} record"
+    def get(name) = "Get a single #{name} record by ID"
+    def update(name) = "Update an existing #{name} record"
+    def delete(name) = "Delete an existing #{name} record"
+  end
+end

data/lib/odata_duty/property/single_prop.rb

@@ -5,9 +5,10 @@ module OdataDuty
 
     class SingleProp
       attr_reader :name, :nullable, :calling_method, :line__defined__at, :raw_type, :type,
-                  :set_type, :method_name, :mutability
+                  :set_type, :method_name, :mutability, :description
 
-      def initialize(name, type, line__defined__at:, nullable:, method:, mutability:)
+      def initialize(name, type, line__defined__at:, nullable:, method:, mutability:,
+                     description:)
         @line__defined__at = line__defined__at
         @name = name.to_sym
         @calling_method = method if method.respond_to?(:call)
@@ -15,6 +16,7 @@ module OdataDuty
         @method_name = (method || name).to_sym
         @nullable = nullable ? true : false
         @mutability = mutability
+        @description = description
         load_type_instance_vars(type)
       end
 
@@ -104,6 +106,7 @@ module OdataDuty
         to_oas2_type.dup.tap do |oas2|
           oas2.merge!('readOnly' => true) if computed?
           oas2.merge!('x-nullable' => true) if nullable
+          oas2.merge!('description' => description) if description
         end
       end
 

data/lib/odata_duty/property.rb

@@ -8,7 +8,7 @@ module OdataDuty
     MUTABILITIES_LIST = MUTABILITIES.map(&:inspect).join(', ').freeze
 
     def self.new(name, type = String, line__defined__at: nil, nullable: true, method: nil,
-                 computed: :unset, mutability: :unset)
+                 computed: :unset, mutability: :unset, description: nil)
       unless valid_name?(name)
         raise InvalidNCNamesError, "\"#{name}\" is not a valid property name"
       end
@@ -18,7 +18,20 @@ module OdataDuty
                      line__defined__at: line__defined__at,
                      nullable: nullable,
                      method: method,
-                     mutability: resolve_mutability(name, computed, mutability))
+                     mutability: resolve_mutability(name, computed, mutability),
+                     description: resolve_description(name, description))
+    end
+
+    def self.resolve_description(owner_name, description)
+      return if description.nil?
+
+      str = description.to_str if description.respond_to?(:to_str)
+      unless str.is_a?(String) && str.match?(/\S/)
+        raise InvalidDescriptionError,
+              "#{owner_name}: description must be a non-empty string"
+      end
+
+      str
     end
 
     def self.resolve_mutability(name, computed, mutability)

data/lib/odata_duty/schema_builder/complex_type.rb

@@ -27,7 +27,7 @@ module OdataDuty
           'properties' => properties.to_h do |property|
                             [property.name.to_s, property.to_oas2]
                           end
-        }
+        }.tap { |oas2| oas2.merge!('description' => description) if description }
       end
     end
   end

data/lib/odata_duty/schema_builder/data_type.rb

@@ -1,15 +1,16 @@
 module OdataDuty
   module SchemaBuilder
     class DataType
-      attr_reader :name, :_defined_at_
+      attr_reader :name, :_defined_at_, :description
 
-      def initialize(name:)
+      def initialize(name:, description: nil)
         @name = name.clone
         @_defined_at_ = caller.find { |line| !line.include?('/lib/odata_duty/') }
 
-        return if Property.valid_name?(@name)
+        raise InvalidNCNamesError, "\"#{@name}\" is not a valid property name" unless
+          Property.valid_name?(@name)
 
-        raise InvalidNCNamesError, "\"#{@name}\" is not a valid property name"
+        @description = Property.resolve_description(@name, description)
       end
 
       def scalar?; end

data/lib/odata_duty/schema_builder/endpoint.rb

@@ -9,6 +9,7 @@ module OdataDuty
 
       def name = entity_set.name
       def url = entity_set.url
+      def description = entity_set.description
 
       def new_entity_set(context:)
         entity_set.resolver_class.new(context: context, init_args: entity_set.init_args)

data/lib/odata_duty/schema_builder/entity_set.rb

@@ -4,15 +4,17 @@ require_relative 'container'
 module OdataDuty
   module SchemaBuilder
     class EntitySet < Container
-      attr_reader :entity_type, :url, :resolver, :init_args
+      attr_reader :entity_type, :url, :resolver, :init_args, :description
 
-      def initialize(entity_type:, resolver:, name: nil, url: nil, init_args: nil)
+      def initialize(entity_type:, resolver:, name: nil, url: nil, init_args: nil,
+                     description: nil)
         @resolver = resolver.clone
         name = name&.to_s || @resolver.split('::').last.sub(/Resolver\z/, '')
         super(name: name)
         @url = (url&.to_s || @name).clone
         @entity_type = entity_type
         @init_args = init_args
+        @description = Property.resolve_description(@name, description)
       end
 
       def entity_type_name = entity_type.name

data/lib/odata_duty/schema_builder/enum_type.rb

@@ -10,8 +10,8 @@ module OdataDuty
         @members = []
       end
 
-      def member(*)
-        @members << EnumMember.new(*)
+      def member(...)
+        @members << EnumMember.new(...)
       end
 
       def scalar?
@@ -25,7 +25,9 @@ module OdataDuty
       end
 
       def to_oas2
-        { 'type' => 'string', 'enum' => members.map(&:name) }
+        { 'type' => 'string', 'enum' => members.map(&:name) }.tap do |hash|
+          hash['description'] = description if description
+        end
       end
     end
   end

data/lib/odata_duty/schema_builder.rb

@@ -11,7 +11,7 @@ module OdataDuty
     end
 
     class Schema
-      attr_reader :namespace, :host, :scheme, :base_path, :base_url, :types
+      attr_reader :namespace, :host, :scheme, :base_path, :base_url, :types, :description
       attr_accessor :version, :title
 
       def initialize(namespace:, host: 'localhost', scheme: 'https', base_path: '')
@@ -24,6 +24,10 @@ module OdataDuty
         @containers = {}
       end
 
+      def description=(text)
+        @description = Property.resolve_description(namespace, text)
+      end
+
       def inspect
         "#<#{self.class} @namespace=#{@namespace} @base_path=#{@base_path} \
  containers=#{@containers.keys} types=#{@types.keys}>"

data/lib/odata_duty.rb

@@ -35,6 +35,11 @@ module OdataDuty
       @url
     end
 
+    def self.description(text = nil)
+      @description = Property.resolve_description(__metadata.name, text) unless text.nil?
+      @description
+    end
+
     class Metadata
       attr_reader :entity_set
 
@@ -42,6 +47,10 @@ module OdataDuty
         @entity_set = entity_set
       end
 
+      def description
+        entity_set.description
+      end
+
       def metadata_types
         [entity_type].map(&:__metadata).flat_map(&:metadata_types)
       end
@@ -118,44 +127,14 @@ module OdataDuty
         raise ResourceNotFoundError, "No such entity #{id}" unless result
       end
 
-      def supports_search?
-        # Check if the entity set class supports search by looking for the od_search method
-        entity_set.method_defined?(:od_search)
-      end
-
-      def supports_filter_or?
-        entity_set.method_defined?(:od_filter_or)
-      end
-
-      def supports_collection?
-        # Check if the entity set class supports read by looking for the collection method
-        entity_set.method_defined?(:collection)
-      end
-
-      def supports_individual?
-        # Check if the entity set class supports read-by-id via the individual method
-        entity_set.method_defined?(:individual)
-      end
-
-      def supports_count?
-        # Check if the entity set class supports counting via the count method
-        entity_set.method_defined?(:count)
-      end
-
-      def supports_create?
-        # Check if the entity set class supports create by looking for the create method
-        entity_set.method_defined?(:create)
-      end
-
-      def supports_update?
-        # Check if the entity set class supports update by looking for the update method
-        entity_set.method_defined?(:update)
-      end
-
-      def supports_delete?
-        # Check if the entity set class supports delete by looking for the delete method
-        entity_set.method_defined?(:delete)
-      end
+      def supports_search? = entity_set.method_defined?(:od_search)
+      def supports_filter_or? = entity_set.method_defined?(:od_filter_or)
+      def supports_collection? = entity_set.method_defined?(:collection)
+      def supports_individual? = entity_set.method_defined?(:individual)
+      def supports_count? = entity_set.method_defined?(:count)
+      def supports_create? = entity_set.method_defined?(:create)
+      def supports_update? = entity_set.method_defined?(:update)
+      def supports_delete? = entity_set.method_defined?(:delete)
 
       def non_insertable_property_names
         @non_insertable_property_names ||=
@@ -206,6 +185,11 @@ module OdataDuty
       @title
     end
 
+    def self.description(text = nil)
+      @description = Property.resolve_description(namespace, text) unless text.nil?
+      @description
+    end
+
     def self.entity_sets(entity_sets = nil)
       @entity_sets = entity_sets.uniq if entity_sets
       @entity_sets
@@ -225,6 +209,7 @@ module OdataDuty
 
       def version = schema.version
       def title = schema.title
+      def description = schema.description
 
       def namespace
         schema.namespace
@@ -272,7 +257,7 @@ module OdataDuty
       metadata = __metadata
       metadata.check_names
 
-      ERB.new(File.read("#{__dir__}/metadata.xml.erb")).result(binding)
+      EdmxSchema.metadata_xml(metadata)
     end
 
     def self.index_hash(metadata_url)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: odata_duty
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Grant Petersen-Speelman
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -121,6 +121,7 @@ files:
 - lib/odata_duty/filter.rb
 - lib/odata_duty/filter_predicate.rb
 - lib/odata_duty/mapper_builder.rb
+- lib/odata_duty/mcp_identifier_validator.rb
 - lib/odata_duty/mcp_input_schemas.rb
 - lib/odata_duty/mcp_server_builder.rb
 - lib/odata_duty/oas2.rb
@@ -129,6 +130,7 @@ files:
 - lib/odata_duty/oas2/individual_delete_path.rb
 - lib/odata_duty/oas2/individual_get_path.rb
 - lib/odata_duty/oas2/individual_patch_path.rb
+- lib/odata_duty/operation_verbs.rb
 - lib/odata_duty/parslet_search_expression.rb
 - lib/odata_duty/property.rb
 - lib/odata_duty/property/collection_prop.rb