mcp_toolkit 0.4.0 → 0.5.0

data/lib/mcp_toolkit/list_executor.rb

@@ -66,10 +66,20 @@ class McpToolkit::ListExecutor
     relation
   end
 
-  # Order by `id` when the primary key is numeric; otherwise by `created_at`
-  # (a non-numeric PK does not sort meaningfully).
+  # Order by `id` when the primary key is numeric; otherwise per
+  # `config.non_numeric_pk_order`: `created_at` with the primary key as a
+  # tiebreaker (default — rows bulk-inserted in one transaction share a
+  # `created_at`, and without a total order offset pagination could duplicate
+  # or skip rows), or the primary key alone for a host preserving a pre-gem
+  # order-by-id contract. `numeric_primary_key?` returning false guarantees the
+  # model exposes a non-nil primary key, so it can be read directly here.
   def apply_order(relation)
-    relation.order(numeric_primary_key? ? :id : :created_at)
+    return relation.order(:id) if numeric_primary_key?
+
+    pk = resource.model.primary_key.to_sym
+    return relation.order(pk) if McpToolkit.config.non_numeric_pk_order == :primary_key
+
+    relation.order(:created_at, pk)
   end
 
   def numeric_primary_key?
@@ -98,9 +108,10 @@ class McpToolkit::ListExecutor
 
     mapping = resource.filterable_columns
     validate_filter_keys!(filter, mapping)
+    validate_filter_companions!(filter)
 
     filter.each do |request_key, value|
-      next if value.nil? || value == ""
+      next if skipped_filter_value?(value)
 
       column = mapping[request_key.to_sym]
       relation = McpToolkit::Filtering.apply(relation, column, value)
@@ -108,6 +119,35 @@ class McpToolkit::ListExecutor
     relation
   end
 
+  # Under :tokenized semantics an empty string means "no filter" (a JSON null
+  # still flows through as an IS NULL filter, like the "null" token — see
+  # McpToolkit::Filtering); under :literal every value reaches the WHERE clause
+  # verbatim.
+  def skipped_filter_value?(value)
+    value == "" && McpToolkit.config.bare_filter_value_semantics != :literal
+  end
+
+  # A filter key may declare a companion key it cannot be used without (e.g. a
+  # polymorphic foreign key is type-ambiguous without its `*_type`) — see
+  # Resource#filter_requirements. Rejected up front rather than producing a
+  # subtly wrong WHERE. A key whose value the apply loop will SKIP counts as
+  # not provided — a skipped ("" under :tokenized) companion must not satisfy
+  # the requirement, or the FK would be applied alone: exactly the
+  # type-ambiguous WHERE the requirement exists to prevent.
+  def validate_filter_companions!(filter)
+    requirements = resource.filter_requirements
+    return if requirements.empty?
+
+    provided = filter.reject { |_key, value| skipped_filter_value?(value) }.keys.map(&:to_sym)
+    requirements.each do |key, required|
+      next unless provided.include?(key)
+      next if provided.include?(required)
+
+      raise McpToolkit::Errors::InvalidParams,
+            "filter attribute #{key} requires #{required} to also be provided"
+    end
+  end
+
   def validate_filter_keys!(filter, mapping)
     keys = filter.keys.map(&:to_sym)
     unknown = keys - mapping.keys
@@ -123,6 +163,10 @@ class McpToolkit::ListExecutor
     return relation if params[:ids].blank?
 
     ids = params[:ids].to_s.split(",").map(&:strip).compact_blank
+    # Bound the IN-set the same way the per-attribute filters are bounded — the
+    # top-level `ids` param builds `WHERE id IN (...)` on its own path, so it
+    # must honor config.max_filter_values too (else it's an unbounded IN clause).
+    McpToolkit::Filtering.enforce_filter_limit!(ids.length, McpToolkit.config)
     ids.empty? ? relation : relation.where(id: ids)
   end
 

data/lib/mcp_toolkit/resource.rb

@@ -42,6 +42,8 @@ class McpToolkit::Resource
     @superusers_only = false
     @filterable = {}
     @filterable_source = nil
+    @filter_requirements = {}
+    @filter_requirements_source = nil
     @custom_filters = {}
     @required_permissions_scope = nil
     @extras = {}
@@ -194,6 +196,35 @@ class McpToolkit::Resource
     filterable_columns.keys.sort
   end
 
+  # Declares companion-key requirements for filter keys: a request-facing key
+  # that is only valid when another key is passed alongside it (the canonical
+  # case is a polymorphic foreign key, type-ambiguous without its `*_type`):
+  #
+  #   filter_requirements created_by_id: :created_by_type
+  #
+  # The list executor rejects a filter using the key without its companion, and
+  # `resource_schema` surfaces the requirement (`relationships[].filter.requires`)
+  # so a client can discover it. The companion key MUST itself be declared
+  # `filterable` — otherwise the requirement is unsatisfiable (the executor
+  # rejects the companion as an unknown key) while the schema still advertises
+  # it. Like `filterable`, accepts a Hash (merged now) OR a callable returning
+  # one (resolved lazily on first successful read, then memoized) so a host can
+  # derive the map without touching the DB at boot. Read with no arg.
+  def filter_requirements(mapping = nil, &block)
+    source = block || mapping
+    if source.nil?
+      resolve_filter_requirements_source!
+      return @filter_requirements
+    end
+
+    if source.respond_to?(:call)
+      @filter_requirements_source = source
+    else
+      merge_filter_requirements!(source)
+    end
+    self
+  end
+
   # Request-facing filter key (symbol) => backing column (symbol). Consumed by
   # the list executor to build the WHERE clause.
   def filterable_columns
@@ -229,19 +260,37 @@ class McpToolkit::Resource
 
   private
 
-  # Resolves a lazily-provided filterable source (a callable) exactly once — on the
-  # first `filterable_columns` / `filterable_keys` read — then drops it, so later
-  # reads are pure Hash access. This is what keeps a DB-derived map (e.g.
-  # `Model.column_names`) out of registration/boot time.
+  # Resolves a lazily-provided filterable source (a callable) on the first
+  # SUCCESSFUL `filterable_columns` / `filterable_keys` read — then drops it, so
+  # later reads are pure Hash access. This is what keeps a DB-derived map (e.g.
+  # `Model.column_names`) out of registration/boot time. The source is cleared
+  # only AFTER it returns: a raising callable (a transient DB hiccup) stays
+  # registered and is retried on the next read, instead of permanently and
+  # silently resolving the allowlist to `{}`.
   def resolve_filterable_source!
     return unless @filterable_source
 
-    source = @filterable_source
+    resolved = @filterable_source.call || {}
     @filterable_source = nil
-    merge_filterable!(source.call || {})
+    merge_filterable!(resolved)
   end
 
   def merge_filterable!(mapping)
     mapping.each { |request_key, column| @filterable[request_key.to_sym] = column.to_sym }
   end
+
+  # Same lazy-resolution contract as the filterable source: resolved on the
+  # first successful read, cleared only after the callable returns so a
+  # transient failure is retried rather than silently dropping the map.
+  def resolve_filter_requirements_source!
+    return unless @filter_requirements_source
+
+    resolved = @filter_requirements_source.call || {}
+    @filter_requirements_source = nil
+    merge_filter_requirements!(resolved)
+  end
+
+  def merge_filter_requirements!(mapping)
+    mapping.each { |key, required| @filter_requirements[key.to_sym] = required.to_sym }
+  end
 end

data/lib/mcp_toolkit/resource_schema.rb

@@ -41,9 +41,12 @@ class McpToolkit::ResourceSchema
       note: resource.note,
       attributes:,
       relationships:,
+      resource_filters:,
       standard_filters: STANDARD_FILTERS,
+      sparse_fieldsets: true,
+      filter_examples:,
       filters:
-    }
+    }.compact
   end
 
   private
@@ -51,7 +54,7 @@ class McpToolkit::ResourceSchema
   attr_reader :resource, :model, :registry
 
   def attributes
-    resource.attribute_names.map { |name| attribute_schema(name) }
+    @attributes ||= resource.attribute_names.map { |name| attribute_schema(name) }
   end
 
   def attribute_schema(name)
@@ -62,18 +65,18 @@ class McpToolkit::ResourceSchema
       format: type ? TYPE_FORMATS[type] : nil,
       filterable: filterable_column_for(name).present?,
       operators: operators_for(name)
-    }.compact
+    }
   end
 
   # The filter operators an attribute accepts, derived from the backing column's
-  # type via McpToolkit::Filtering::OPERATORS_BY_TYPE. `[]` for a non-filterable
-  # attribute (or one whose column type has no operator set) — self-describing so
-  # a client knows exactly which `{ op:, value: }` conditions `list` will accept.
+  # type via McpToolkit::Filtering.operators_for. `[]` for a non-filterable
+  # attribute (or one with no backing column) — self-describing so a client
+  # knows exactly which `{ op:, value: }` conditions `list` will accept.
   def operators_for(attribute_name)
     pair = filterable_column_for(attribute_name)
     return [] unless pair
 
-    McpToolkit::Filtering::OPERATORS_BY_TYPE.fetch(column_type(pair.last), [])
+    McpToolkit::Filtering.operators_for(column_type(pair.last))
   end
 
   # Per-attribute equality filters this resource accepts on the `list` tool's
@@ -92,6 +95,88 @@ class McpToolkit::ResourceSchema
     end
   end
 
+  # The resource's custom filters (Resource#filter) — resource-specific filters
+  # passed as TOP-LEVEL params of the `list` tool (NOT inside `filter`), each
+  # applied by a host-supplied block. Surfaced with name/type/description so a
+  # client can discover them; `[]` for a resource that declares none.
+  # Entries keep nil type/description keys (rather than compacting) — the
+  # pre-gem contract emitted them, and an always-present shape is easier for a
+  # client to consume.
+  def resource_filters
+    resource.custom_filters.each_value.map do |custom_filter|
+      {
+        name: custom_filter.name.to_s,
+        type: custom_filter.type&.to_s,
+        description: custom_filter.description
+      }
+    end
+  end
+
+  # Ready-to-use `filter` payload examples built from this resource's own
+  # filterable attributes and relationships, so a client can copy a working
+  # shape instead of deriving it from the operator lists.
+  def filter_examples
+    [equality_example, comparison_example, range_example, relationship_example].compact
+  end
+
+  def equality_example
+    attribute = example_attributes.find { |candidate| candidate[:type] == "string" } || example_attributes.first
+    return unless attribute
+
+    { attribute[:name] => sample_value(attribute[:type]) }
+  end
+
+  def comparison_example
+    attribute = comparison_attribute
+    return unless attribute
+
+    { attribute[:name] => { op: "gt", value: sample_value(attribute[:type]) } }
+  end
+
+  def range_example
+    attribute = comparison_attribute
+    return unless attribute
+
+    {
+      attribute[:name] => [
+        { op: "gteq", value: sample_value(attribute[:type]) },
+        { op: "lt", value: sample_value(attribute[:type]) }
+      ]
+    }
+  end
+
+  def relationship_example
+    relationship = relationships.find { |candidate| candidate[:filter] }
+    return unless relationship
+
+    example = { relationship[:filter][:keys].first => 1 }
+    example[relationship[:filter][:requires]] = "User" if relationship[:filter][:requires]
+    example
+  end
+
+  def filterable_attributes
+    attributes.select { |attribute| attribute[:filterable] }
+  end
+
+  # `id` is filterable but uninteresting as an example (use the `ids` filter for that).
+  def example_attributes
+    filterable_attributes.reject { |attribute| attribute[:name] == :id }
+  end
+
+  def comparison_attribute
+    example_attributes.find { |attribute| attribute[:operators].include?("gt") }
+  end
+
+  def sample_value(type)
+    case type.to_s
+    when "integer" then 1
+    when "decimal", "float" then "100.0"
+    when "boolean" then true
+    when "datetime", "date" then "2026-01-01T00:00:00Z"
+    else "..."
+    end
+  end
+
   # Backing column for a serialized attribute that is also a filter key, if any.
   # A filter key may be a public alias (e.g. booking_id -> synced_booking_id) so
   # we match on either the request key or the column.
@@ -102,22 +187,46 @@ class McpToolkit::ResourceSchema
   end
 
   def relationships
-    resource.association_descriptors.map { |association| relationship_schema(association) }
+    @relationships ||= resource.association_descriptors.map { |association| relationship_schema(association) }
   end
 
-  # One relationship entry. Beyond the link key/kind/polymorphic flag it now also
-  # names the `target_resource` — the registered resource this link resolves to,
-  # callable via `list`/`get` — so e.g. a `scheduled_notifications.notification`
-  # link is discoverably the `notifications` resource rather than a name to guess.
-  # It is omitted (additive/backward-compatible) when the target can't be resolved
-  # (e.g. a polymorphic link).
+  # One relationship entry: the link key/kind/polymorphic flag, the registered
+  # resource the link resolves to — emitted BOTH as `resource` (nullable) and,
+  # when resolved, as `target_resource` (so e.g. a
+  # `scheduled_notifications.notification` link is discoverably the
+  # `notifications` resource rather than a name to guess) — and, when the
+  # link's foreign key is filterable, a `filter` block telling a client HOW to
+  # filter by the relationship (see #relationship_filter).
   def relationship_schema(association)
     target = target_resource_for(association)
-    {
+    schema = {
       name: association.links_key,
       kind: association.type.to_s,
       polymorphic: association.polymorphic || false,
-      target_resource: target&.name
+      resource: target&.name,
+      filter: relationship_filter(association.links_key)
+    }
+    schema[:target_resource] = target.name if target
+    schema
+  end
+
+  # How to filter by a relationship, when its foreign key is in the filter
+  # allowlist: the accepted request keys (the FK, plus the bare link name when
+  # aliased), the backing column's type, its operators, and — for a key that
+  # cannot be used alone (e.g. a polymorphic FK needing its `*_type`) — the
+  # companion key it `requires` (see Resource#filter_requirements).
+  def relationship_filter(name)
+    id_key = :"#{name}_id"
+    column = resource.filterable_columns[id_key]
+    return nil unless column
+
+    keys = [id_key]
+    keys << name.to_sym if resource.filterable_columns.key?(name.to_sym)
+    {
+      keys:,
+      type: column_type(column).to_s,
+      operators: operators_for(id_key),
+      requires: resource.filter_requirements[id_key]
     }.compact
   end
 

data/lib/mcp_toolkit/serializer/association_descriptor.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The association shape the gem reads off a serializer's
+# `declared_associations` (ResourceSchema's relationship entries,
+# FieldSelection's valid `fields` names). A host adapting its OWN serializer
+# framework builds these rather than re-deriving the duck-type by hand:
+# `links_key` / `type` / `polymorphic` / `name`, plus an optional `serializer`
+# responding to `model_class` (see TargetRef) so the target resource resolves.
+McpToolkit::Serializer::AssociationDescriptor = Struct.new(
+  :name, :type, :polymorphic, :links_key, :serializer, keyword_init: true
+)

data/lib/mcp_toolkit/serializer/target_ref.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Minimal object satisfying the gem's `association.serializer.model_class`
+# probe (ResourceSchema's target-resource resolution): carries the model an
+# association resolves to. Pair with AssociationDescriptor when adapting a
+# host serializer framework.
+McpToolkit::Serializer::TargetRef = Struct.new(:model_class)

data/lib/mcp_toolkit/session.rb

@@ -28,9 +28,9 @@ class McpToolkit::Session
     stored = config.cache_store.read(cache_key(id))
     return nil unless stored
 
-    # Sliding expiry: bump TTL on every successful lookup.
+    # Sliding expiry: bump TTL on every successful lookup, re-writing the row
+    # untouched.
     config.cache_store.write(cache_key(id), stored, expires_in: config.session_ttl)
-    # `data` defaults to {} for legacy rows written before the payload existed.
     new(id:, data: stored[:data] || {})
   end
 

data/lib/mcp_toolkit/tool_reference_rewriter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Rewrites backticked generic-tool references ("use the `resources` tool") inside
+# tool prose so they always name the tools exactly as they appear in the serving
+# server's `tools/list`. Two serving paths need this: the authority's own generic
+# tools when the host configures a `generic_tool_name_prefix` (a client would
+# otherwise be pointed at an unprefixed tool that does not exist), and the
+# gateway's aggregated upstream tools, whose names are re-keyed into the
+# `<app>__<tool>` namespace while their prose would otherwise keep naming the
+# upstream's bare tools.
+#
+# Only EXACT backticked base names are rewritten; other backticked terms
+# (`resource`, `filter`, `target_resource`, ...) never match.
+module McpToolkit::ToolReferenceRewriter
+  GENERIC_TOOL_REFERENCES = /`(resource_schema|resources|list|get)`/
+
+  module_function
+
+  # Rewrites `node` (a String, or a Hash/Array structure such as a tool
+  # definition or input schema, walked recursively) with `name_prefix` applied to
+  # every backticked generic-tool reference. Non-string leaves pass through
+  # untouched; an empty prefix returns the node verbatim.
+  def rewrite(node, name_prefix)
+    return node if name_prefix.to_s.empty?
+
+    case node
+    when String then node.gsub(GENERIC_TOOL_REFERENCES) { "`#{name_prefix}#{Regexp.last_match(1)}`" }
+    when Hash then node.transform_values { |value| rewrite(value, name_prefix) }
+    when Array then node.map { |value| rewrite(value, name_prefix) }
+    else node
+    end
+  end
+end

data/lib/mcp_toolkit/tools/authority_base.rb

@@ -105,6 +105,15 @@ class McpToolkit::Tools::AuthorityBase
     raise McpToolkit::Protocol::InvalidRequest, "#{resource.name} is restricted to superuser (user-scoped) MCP tokens"
   end
 
+  # ArgumentErrors Ruby itself raises while binding the request arguments to the
+  # subclass's `#call` signature: a missing/unknown keyword or wrong arity. Their
+  # messages carry only keyword names (the tool's own declared params) and counts,
+  # so surfacing them tells a client how to fix the call. Every OTHER ArgumentError
+  # is raised from inside the tool's business logic (e.g. `Integer("x")`) and its
+  # message may carry SQL, internal class names, or a value — so it is sanitized
+  # like any unexpected error rather than relayed verbatim.
+  ARGUMENT_BINDING_ERROR_MESSAGE = /\A(missing keyword|unknown keyword|wrong number of arguments)/
+
   # Runs the tool's business logic (the subclass's `#call`) with error mapping.
   # Arrives with symbol-keyed arguments from the dispatcher.
   def execute(**arguments)
@@ -114,9 +123,11 @@ class McpToolkit::Tools::AuthorityBase
     # (e.g. InvalidParams); let it bubble untouched so the client sees it.
     raise
   rescue ArgumentError => e
-    raise McpToolkit::Protocol::InvalidParams, e.message
+    raise McpToolkit::Protocol::InvalidParams, e.message if ARGUMENT_BINDING_ERROR_MESSAGE.match?(e.message)
+
+    raise sanitized_internal_error(e)
   rescue StandardError => e
-    raise McpToolkit::Protocol::InternalError, e.message
+    raise sanitized_internal_error(e)
   end
 
   # The subclass implements its business logic here, receiving the tool arguments
@@ -124,4 +135,14 @@ class McpToolkit::Tools::AuthorityBase
   def call(**_arguments)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
+
+  private
+
+  # An UNEXPECTED error's message may carry SQL, internal class names, or a
+  # hostname — it must not reach the caller (the dispatcher relays a
+  # Protocol::Error's message verbatim). Log the detail; return a generic error.
+  def sanitized_internal_error(error)
+    McpToolkit.config.logger&.error("MCP tool #{self.class} error: #{error.message}\n#{error.backtrace&.join("\n")}")
+    McpToolkit::Protocol::InternalError.new("Internal error")
+  end
 end

data/lib/mcp_toolkit/tools/base.rb

@@ -26,7 +26,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # `required_scope` is the explicitly-declared scope a token must carry (the
   # caller resolves it from the resource — see Registry#required_scope_for).
   # Empty/nil => no scope check (authorized_for_scope? treats "" as a pass).
-  def self.with_account(server_context, account_id: nil, required_scope: nil)
+  def self.with_account(server_context, account_id: nil, required_scope: nil, resource: nil)
     config = config_from(server_context)
     context = McpToolkit::Auth::Authenticator.call(
       token: server_context[:bearer_token],
@@ -40,6 +40,9 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
+    superuser_refusal = superuser_only_refusal(resource, context.introspection)
+    return superuser_refusal if superuser_refusal
+
     text_response(yield(context.scope_root))
   rescue McpToolkit::Errors::Unauthorized => e
     error_response("Unauthorized: #{e.message}")
@@ -52,7 +55,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # which reveal shape, not tenant data, so a superuser shouldn't have to pin an
   # account just to discover what exists. Empty/nil `required_scope` => no scope
   # check.
-  def self.with_authentication(server_context, required_scope: nil)
+  def self.with_authentication(server_context, required_scope: nil, resource: nil)
     config = config_from(server_context)
     introspection = McpToolkit::Auth::Introspection.call(server_context[:bearer_token], config:)
     return error_response("Unauthorized: invalid or expired token") unless introspection.valid?
@@ -61,11 +64,28 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
-    text_response(yield)
+    superuser_refusal = superuser_only_refusal(resource, introspection)
+    return superuser_refusal if superuser_refusal
+
+    # Yields the introspection so a discovery tool (`resources`) can HIDE
+    # superuser-only resources from a non-superuser caller (get/list/resource_schema
+    # instead pass `resource:` above to REFUSE a specific one).
+    text_response(yield(introspection))
   rescue McpToolkit::Errors::InvalidParams => e
     error_response("Invalid request: #{e.message}")
   end
 
+  # Refuses a superuser-only resource for a non-superuser caller (get / list /
+  # resource_schema); nil = allowed. Mirrors the authority path's
+  # `ensure_resource_accessible!`. `resources` HIDES such resources instead of
+  # refusing — it filters on `introspection.superuser?` directly.
+  def self.superuser_only_refusal(resource, introspection)
+    return nil unless resource&.superusers_only?
+    return nil if introspection.superuser?
+
+    error_response("Unauthorized: #{resource.name} is restricted to superuser (user-scoped) MCP tokens")
+  end
+
   def self.text_response(payload)
     text = payload.is_a?(String) ? payload : JSON.generate(payload)
     MCP::Tool::Response.new([{ type: "text", text: }])

data/lib/mcp_toolkit/tools/get.rb

@@ -48,7 +48,7 @@ class McpToolkit::Tools::Get < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::GetExecutor.call(resource: descriptor, scope_root:, id:, fields:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/list.rb

@@ -15,11 +15,26 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       - limit: page size (default 25, max 100)
       - offset: pagination offset (default 0)
 
-    Per-attribute equality filters:
-      - filter: an object of { <key>: <value> } exact-match filters, applied ON TOP of the
-        account scope (they can only narrow, never widen). Each resource advertises its
-        available filter keys via `resource_schema` (the `filters` array). Unknown keys are
-        rejected.
+    Per-attribute filters:
+      - filter: an object of { <key>: <value> } filters, applied ON TOP of the account scope
+        (they can only narrow, never widen). Each resource advertises its available filter keys
+        and operators via `resource_schema`. Unknown keys are rejected.
+      - A bare value matches by equality. A comma-separated string or an array of scalars
+        matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+        { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+        records where the value is NULL.
+      - An operator condition is an object { "op": <operator>, "value": <value> }, e.g.
+        { "price": { "op": "gteq", "value": 100 } }. An array of conditions ANDs them into a
+        range: { "price": [{ "op": "gteq", "value": 100 }, { "op": "lt", "value": 200 }] }.
+        Each attribute's supported operators are listed in `resource_schema`.
+      - Some filter keys require a companion key (e.g. a polymorphic id and its type) —
+        `resource_schema` advertises these under a relationship's `filter.requires`; pass
+        both keys together.
+
+    Resource-specific filters:
+      - Some resources accept additional filters advertised in `resource_schema` under
+        `resource_filters`. Pass each as a TOP-LEVEL argument (NOT inside `filter`), e.g.
+        { "resource": "...", "<name>": <value> }.
 
     Sparse fieldset:
       - fields: names of the attributes and/or relationships to include in each record, as an
@@ -50,8 +65,8 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       },
       filter: {
         type: "object",
-        description: "Per-attribute exact-match equality filters, e.g. { \"booking_id\": 42 }. " \
-                     "See a resource's `resource_schema` `filters` for the keys it accepts.",
+        description: "Per-attribute filters, e.g. { \"booking_id\": 42 }. See a resource's " \
+                     "`resource_schema` `filters` for the keys and operators it accepts.",
         additionalProperties: true
       },
       limit: { type: "integer", description: "Page size (default 25, max 100)" },
@@ -65,7 +80,10 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
                      "resource's `resource_schema` for valid attribute and relationship names."
       }
     },
-    required: ["resource"]
+    required: ["resource"],
+    # Resource-specific filters (resource_schema's `resource_filters`) arrive as
+    # top-level arguments, so the schema must not advertise a closed shape.
+    additionalProperties: true
   )
 
   def self.call(server_context:, resource: nil, account_id: nil, **params)
@@ -74,7 +92,7 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::ListExecutor.call(resource: descriptor, scope_root:, params:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/resource_schema.rb

@@ -7,11 +7,19 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
   description <<~DESC.strip
     Describe a single read-only resource in detail. Pass the resource name as `resource` (use
     the `resources` tool to discover names). Returns:
-      - attributes: every field in the response, each with its `type` and a value `format` hint
+      - attributes: every field in the response, each with its `type`, a value `format` hint,
+        whether it is `filterable`, and the filter `operators` it accepts
       - relationships: associated resources emitted in the record's `links`; each names the
         `target_resource` it resolves to (callable via `list`/`get`)
       - standard_filters: ids, updated_since, limit, offset (accepted by the `list` tool)
-      - filters: the per-attribute equality filter keys the `list` tool accepts
+      - filters: the per-attribute equality/operator filter keys the `list` tool accepts in
+        its `filter` argument
+      - resource_filters: resource-specific filters, if any — each is passed as a TOP-LEVEL
+        argument of the `list` tool (NOT inside `filter`), e.g. { "resource": "...",
+        "<name>": <value> }
+      - filter_examples: ready-to-use `filter` payloads for this resource
+    A relationship's `filter` block lists the keys that filter by it; when it names a
+    `requires` key (e.g. a polymorphic id needing its type), pass BOTH keys together.
     The `attributes` and `relationships` names are also the valid values for the `fields` sparse
     fieldset argument on `get` / `list`. Call this before `list` to learn a resource's shape.
   DESC
@@ -31,7 +39,8 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
     # Resolve the resource FIRST so its effective required scope gates discovery
     # of THIS resource's shape (and an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
-    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor)) do
+    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor),
+                                        resource: descriptor) do
       McpToolkit::ResourceSchema.call(descriptor, registry: config.registry)
     end
   rescue McpToolkit::Errors::InvalidParams => e