odata_duty 0.30.1 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24b2763892ae6cc0088ab89de9281a39c0ecf100406950f6263e8a364bdd2abc
-  data.tar.gz: 185bee55b726314b02f5add982464b0b949189a592fcff7a1ba9f6b33939b2b7
+  metadata.gz: 5fc1895bad51713ec481fdb8d68fc3ba169512821b6da0411c1123a3589ec39b
+  data.tar.gz: 686c02c58e32d49007257aec13415afb1ad57469cca572c7caf2fcb0f6192e51
 SHA512:
-  metadata.gz: b3490f5fb35ca308175a3c08e3bc0fdcbc822b80334b1642ff073c02281e0d54d60b78a8c9155efac8c713ca1b3b4e66fb67ac99233497bd542620369e25b446
-  data.tar.gz: 92f65ccdb8c6efb24fcea1f39af2e16651f7b4e937e7304998f56e26cccdcf2c19a7d36d84013b314f53f2bf6689d78958b3c144e3a1233aed781a5ae3f45501
+  metadata.gz: 913eadf1694619c01556d8988b1d6a4cc77b7f9697c496dad0735a6be0a812838a26341cb87c460fb0662a73db6541720fecefa46beee0edc61737799b514427
+  data.tar.gz: 3c497e407c716e90c7d27f1d94bbf9279742bfd6ee7699d2993e60fd877079871c4c70b7a0b2e56bb13b0f18f9cc9f6ce4312638feb7d9e07318f736fe427913

data/CHANGELOG.md

@@ -6,6 +6,67 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-09-08
+
+### Added
+- `odata_skiptoken` argument on the MCP `list_<Set>` tool for entity sets that define
+  `od_next_link_skiptoken`, so an agent can follow a `@odata.nextLink` over MCP instead of
+  hitting a dead end (#76).
+- The MCP server `instructions` now describe the supported OData dialect — the `$filter`
+  grammar, `$search`, skiptoken paging, and what is explicitly unsupported — with each line
+  present only when some entity set can serve it (#76).
+- Generated descriptions on every `odata_*` read-tool argument, and `items.enum` of the entity
+  type's property names on `$select`/`odata_select` so an unknown property is rejected before
+  it reaches the service (#76).
+- `doc/using_paging.md`, covering `$top`, `$skip`, `$skiptoken`, and `od_next_link_skiptoken`
+  (#75).
+
+### Changed
+- **Breaking (MCP tool shape):** read tools (`list_`/`count_`/`get_<Set>`) now advertise
+  `odata_filter`, `odata_search`, `odata_top`, `odata_skip`, and `odata_skiptoken` only when
+  the entity set defines the matching hook, rather than offering every option and failing with
+  `NoImplementationError` when it is used. Filterability is inferred from any public
+  `od_filter_*` method. `odata_select` remains ungated (#76).
+- **Breaking (MCP tool shape):** `odata_select` is now an array of property names instead of a
+  comma-separated string (#76).
+- **Breaking (MCP server shape):** `instructions` was previously exactly the schema
+  `description:` and omitted when that was nil; it is now always present and carries the
+  generated dialect description (#76).
+- `$oas2` collection parameters: `$filter` is capability-gated on the same rule, and
+  `$top`/`$skip` carry `minimum: 0` (#76).
+- `$top`/`$skip` are validated as non-negative base-10 integers before dispatching to
+  `od_top`/`od_skip`, raising `InvalidQueryOptionError` for negative, non-numeric, or otherwise
+  malformed values instead of passing them through to consumer hooks (#75).
+
+`$metadata` and REST execution are unchanged — hiding a query-option parameter does not change
+what the service honors or rejects.
+
+## [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 +119,9 @@ 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.32.0...HEAD
+[0.32.0]: https://github.com/NEXL-LTS/odata_duty-ruby/compare/v0.31.0...v0.32.0
+[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/capability_hooks.rb

@@ -0,0 +1,9 @@
+module OdataDuty
+  module CapabilityHooks
+    FILTER_HOOK_PREFIX = 'od_filter_'.freeze
+
+    def self.filterable?(klass)
+      klass.public_instance_methods.any? { |name| name.start_with?(FILTER_HOOK_PREFIX) }
+    end
+  end
+end

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/executor.rb

@@ -207,6 +207,7 @@ module OdataDuty
     end
 
     def apply_top(set_builder, top)
+      validate_non_negative_integer('$top', top)
       if !set_builder.respond_to?(:od_top) && top
         raise NoImplementationError, "$top not implemented for #{set_builder.class}"
       end
@@ -215,6 +216,7 @@ module OdataDuty
     end
 
     def apply_skip(set_builder, skip)
+      validate_non_negative_integer('$skip', skip)
       if !set_builder.respond_to?(:od_skip) && skip
         raise NoImplementationError, "$skip not implemented for #{set_builder.class}"
       end
@@ -222,6 +224,21 @@ module OdataDuty
       set_builder.od_skip(skip) if skip
     end
 
+    def validate_non_negative_integer(name, value)
+      return unless value
+      return if non_negative_integer?(value)
+
+      raise InvalidQueryOptionError, "'#{name}' must be a non-negative integer, got '#{value}'"
+    end
+
+    def non_negative_integer?(value)
+      return value >= 0 if value.is_a?(Integer)
+
+      Integer(value, 10) >= 0
+    rescue ArgumentError
+      false
+    end
+
     def apply_skiptoken(set_builder, skiptoken)
       if !set_builder.respond_to?(:od_skiptoken) && skiptoken
         raise NoImplementationError, "$skiptoken not implemented for #{set_builder.class}"

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

@@ -1,3 +1,5 @@
+require 'odata_duty/mcp_query_options'
+
 module OdataDuty
   module McpInputSchemas
     extend self
@@ -5,25 +7,65 @@ 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.
 
-    def count_input_schema(supports_search:)
-      properties = { '$filter' => { 'type' => 'string' } }
-      properties['$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' }
-      }
-      if supports_search
-        properties['$search'] = { 'type' => 'string',
-                                  'description' => 'Search expression (AND, OR, NOT)' }
+    # `$`-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',
+      '$skiptoken' => 'odata_skiptoken'
+    }.freeze
+
+    UNGATED = nil
+
+    # `[query-option key, capability predicate]` in advertised order; `UNGATED` is always
+    # advertised. The argument shape for each key lives in McpQueryOptions.
+    LIST_QUERY_OPTIONS = [
+      ['$filter', :supports_filter?],
+      ['$select', UNGATED],
+      ['$search', :supports_search?],
+      ['$top', :supports_top?],
+      ['$skip', :supports_skip?],
+      ['$skiptoken', :supports_skiptoken?]
+    ].freeze
+
+    COUNT_QUERY_OPTIONS = [
+      ['$filter', :supports_filter?],
+      ['$search', :supports_search?]
+    ].freeze
+
+    def count_input_schema(endpoint)
+      { 'properties' => supported_query_options(COUNT_QUERY_OPTIONS, endpoint), 'required' => [] }
+    end
+
+    def list_input_schema(endpoint)
+      { 'properties' => supported_query_options(LIST_QUERY_OPTIONS, endpoint), 'required' => [] }
+    end
+
+    def supported_query_options(gates, endpoint)
+      definitions = McpQueryOptions.definitions(endpoint.entity_type)
+      gates.each_with_object({}) do |(key, predicate), properties|
+        next if predicate && !endpoint.public_send(predicate)
+
+        properties[alias_for(key)] = definitions.fetch(key)
+      end
+    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['$top'] = { 'type' => 'integer', 'description' => 'Max records to return' }
-      properties['$skip'] = { 'type' => 'integer', 'description' => 'Records to skip' }
-      { 'properties' => properties, 'required' => [] }
+
+      properties[key] = value
     end
 
     def create_input_schema(entity_type)
@@ -41,13 +83,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 = McpQueryOptions.select_option(entity_type)
+      add_alias!(properties, entity_type, '$select', select_value, tool_name: tool_name)
       { 'properties' => properties, 'required' => [key.name] }
     end
 
@@ -55,5 +95,9 @@ 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
   end
 end

data/lib/odata_duty/mcp_instructions.rb

@@ -0,0 +1,60 @@
+module OdataDuty
+  # Builds the MCP server `instructions` document: the schema's own description followed by a
+  # description of the OData dialect the generated tools actually speak. A per-option line is
+  # included only when at least one entity set in the schema supports that query option, so the
+  # document never advertises a capability no tool exposes.
+  module McpInstructions
+    extend self
+
+    INTRO = 'This service exposes a subset of OData v4. Query options are passed to tools as ' \
+            '`odata_*` arguments (e.g. `odata_filter` is OData `$filter`).'.freeze
+
+    FILTER_LINE = '$filter: predicates of the form `<property> <op> <value>`. Operators: eq, ' \
+                  'ne, gt, ge, lt, le. Combine with all `and` or all `or` — mixing `and` with ' \
+                  '`or` is not supported, nor is parenthesised grouping. Functions (contains, ' \
+                  'startswith, tolower, …), arithmetic and `not` are not supported. String ' \
+                  'literals use single quotes; Edm.Date and Edm.DateTimeOffset values are ISO ' \
+                  '8601 (2024-01-31, 2024-01-31T00:00:00+00:00).'.freeze
+
+    SEARCH_LINE = '$search: terms combined with AND, OR, NOT. Parenthesised groups are not ' \
+                  'supported.'.freeze
+
+    PAGING_LINE = 'Paging: pass odata_skiptoken with the $skiptoken value from a prior ' \
+                  "response's @odata.nextLink.".freeze
+
+    UNSUPPORTED_LINE = '$orderby, $expand, $apply, $compute and $count=true are not ' \
+                       'supported.'.freeze
+
+    CLOSING = 'Each tool advertises only the query options its entity set supports.'.freeze
+
+    # `[line, capability predicate]` in document order; each line is included only when some
+    # endpoint answers true to its predicate.
+    OPTION_LINES = [
+      [FILTER_LINE, :supports_filter?],
+      [SEARCH_LINE, :supports_search?],
+      [PAGING_LINE, :supports_skiptoken?]
+    ].freeze
+
+    def build(schema)
+      [schema.description, dialect(schema)].compact.join("\n\n")
+    end
+
+    def dialect(schema)
+      [INTRO, option_lines(schema).join("\n"), CLOSING].join("\n\n")
+    end
+
+    def option_lines(schema)
+      supported = OPTION_LINES.filter_map do |line, predicate|
+        line if schema.endpoints.any? { |endpoint| advertises?(endpoint, predicate) }
+      end
+      supported + [UNSUPPORTED_LINE]
+    end
+
+    # `$filter` and `$search` reach a set through its `list_`/`count_` tools and paging through
+    # `list_`, all of which need a `collection` method — so a set without one advertises no
+    # query options at all, whatever hooks it defines.
+    def advertises?(endpoint, predicate)
+      endpoint.supports_collection? && endpoint.public_send(predicate)
+    end
+  end
+end

data/lib/odata_duty/mcp_query_options.rb

@@ -0,0 +1,59 @@
+module OdataDuty
+  # Argument definitions for the `odata_*` query-option keys `McpInputSchemas` advertises on the
+  # read tools, keyed by their `$`-prefixed OData spelling. Split out of `McpInputSchemas` so the
+  # `$select` shape has one definition shared by the gated list/count tables and `get_`.
+  module McpQueryOptions
+    extend self
+
+    FILTER_DESCRIPTION =
+      'OData $filter expression; see the service instructions for the grammar. Filtering is ' \
+      'supported for this entity set, but not every property or operator combination is ' \
+      'necessarily implemented — an unsupported combination returns an error rather than an ' \
+      'empty result. Property names are listed under odata_select. ' \
+      "Example: user_name eq 'Alice'".freeze
+
+    SELECT_DESCRIPTION = 'Properties to return; omit for all.'.freeze
+
+    SEARCH_DESCRIPTION =
+      'Free-text $search expression; terms combined with AND, OR, NOT. Parenthesised groups ' \
+      'are not supported.'.freeze
+
+    TOP_DESCRIPTION = 'Maximum number of records to return.'.freeze
+
+    SKIP_DESCRIPTION = 'Number of records to skip before returning results.'.freeze
+
+    SKIPTOKEN_DESCRIPTION =
+      'Continuation token for the next page. Take it from the $skiptoken query parameter of a ' \
+      "prior response's @odata.nextLink.".freeze
+
+    def definitions(entity_type)
+      {
+        '$filter' => string_option(FILTER_DESCRIPTION),
+        '$select' => select_option(entity_type),
+        '$search' => string_option(SEARCH_DESCRIPTION),
+        '$top' => integer_option(TOP_DESCRIPTION),
+        '$skip' => integer_option(SKIP_DESCRIPTION),
+        '$skiptoken' => string_option(SKIPTOKEN_DESCRIPTION)
+      }
+    end
+
+    # An array of property names rather than OData's comma-separated string, so the `enum` can
+    # advertise exactly which names are selectable and the MCP SDK rejects the rest before the
+    # tool handler runs. McpToolArguments joins the array back to `$select`'s OData spelling.
+    def select_option(entity_type)
+      names = entity_type.properties.map { |property| property.name.to_s }
+      { 'type' => 'array', 'description' => SELECT_DESCRIPTION,
+        'items' => { 'type' => 'string', 'enum' => names } }
+    end
+
+    def string_option(description)
+      { 'type' => 'string', 'description' => description }
+    end
+
+    # `minimum` lets the MCP SDK reject a negative paging argument against the tool schema
+    # before the handler runs, where over REST it reaches Executor's InvalidQueryOptionError.
+    def integer_option(description)
+      { 'type' => 'integer', 'minimum' => 0, 'description' => description }
+    end
+  end
+end