rails-agent-kit 0.1.0 → 0.2.0

data/lib/rails_agent_kit/client_config.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module RailsAgentKit
+  # Writes the project-level MCP configuration that starts rails-agent-kit for each supported client.
+  #
+  #   cursor  -> .cursor/mcp.json   ("mcpServers", paths relative to ${workspaceFolder})
+  #   claude  -> .mcp.json          ("mcpServers", started from the project root)
+  #   vscode  -> .vscode/mcp.json   ("servers", paths relative to ${workspaceFolder})
+  #   codex   -> ~/.codex/config.toml is a global file, so its snippet is returned, never written
+  #
+  # Existing files keep every other server. An existing rails-agent-kit entry that differs from the generated
+  # one is left alone unless force: true.
+  class ClientConfig
+    SERVER_NAME = "rails-agent-kit"
+    AGENTS = %w[cursor claude vscode codex].freeze
+    FILES = {
+      "cursor" => [".cursor/mcp.json", "mcpServers"],
+      "claude" => [".mcp.json", "mcpServers"],
+      "vscode" => [".vscode/mcp.json", "servers"]
+    }.freeze
+
+    Result = Struct.new(:agent, :path, :status, :snippet, :message, keyword_init: true)
+
+    # Parses "cursor,claude" or "all" into a list of agents. Raises Error for unknown names.
+    def self.parse_agents(value)
+      names = value.to_s.split(",").map { |a| a.strip.downcase }.reject(&:empty?)
+      return AGENTS.dup if names.empty? || names.include?("all")
+
+      unknown = names - AGENTS
+      raise Error, "unknown agent #{unknown.first.inspect} (supported: #{AGENTS.join(', ')}, all)" if unknown.any?
+
+      names.uniq
+    end
+
+    attr_reader :root
+
+    def initialize(root, force: false, dry_run: false, bundled: nil)
+      @root = File.expand_path(root)
+      @force = force
+      @dry_run = dry_run
+      @bundled = bundled.nil? ? self.class.bundled?(@root) : bundled
+    end
+
+    # True when the app's Gemfile (or Gemfile.lock) includes rails-agent-kit, so the server must run through
+    # `bundle exec`. Otherwise the globally installed executable is used.
+    def self.bundled?(root)
+      lock = File.join(root, "Gemfile.lock")
+      return File.read(lock).match?(/^ {4}rails-agent-kit \(/) if File.file?(lock)
+
+      gemfile = File.join(root, "Gemfile")
+      File.file?(gemfile) && File.read(gemfile).match?(/^\s*gem\s+["']rails-agent-kit["']/)
+    end
+
+    def bundled?
+      @bundled
+    end
+
+    def write(agents)
+      agents.map { |agent| agent == "codex" ? codex_result : write_json(agent) }
+    end
+
+    # The server entry for one client, as a Hash ready to be stored under the client's servers key.
+    def entry_for(agent)
+      case agent
+      when "cursor", "vscode"
+        folder = "${workspaceFolder}"
+        entry = agent == "vscode" ? { "type" => "stdio" } : {}
+        entry.merge(command_for(folder, env: { "BUNDLE_GEMFILE" => "#{folder}/Gemfile" }))
+      when "claude"
+        # Claude Code starts project servers from the project root, so a relative root works for the whole team.
+        command_for(".")
+      else
+        raise Error, "no JSON config for #{agent.inspect}"
+      end
+    end
+
+    def codex_snippet
+      args = bundled? ? ["exec", SERVER_NAME, "--root", root] : ["--root", root]
+      lines = ["[mcp_servers.#{SERVER_NAME}]", "command = #{toml(bundled? ? 'bundle' : SERVER_NAME)}",
+               "args = [#{args.map { |a| toml(a) }.join(', ')}]"]
+      lines << "env = { BUNDLE_GEMFILE = #{toml(File.join(root, 'Gemfile'))} }" if bundled?
+      "#{lines.join("\n")}\n"
+    end
+
+    private
+
+    def command_for(app_root, env: {})
+      return { "command" => SERVER_NAME, "args" => ["--root", app_root] } unless bundled?
+
+      entry = { "command" => "bundle", "args" => ["exec", SERVER_NAME, "--root", app_root] }
+      entry["env"] = env unless env.empty?
+      entry
+    end
+
+    def write_json(agent)
+      relative, key = FILES.fetch(agent)
+      path = File.join(root, relative)
+      entry = entry_for(agent)
+      config = read_json(path)
+      return Result.new(agent: agent, path: path, status: :error, message: config) if config.is_a?(String)
+
+      servers = config[key] ||= {}
+      unless servers.is_a?(Hash)
+        return Result.new(agent: agent, path: path, status: :error, message: "#{key.inspect} is not an object")
+      end
+
+      status =
+        if !File.exist?(path) then :created
+        elsif !servers.key?(SERVER_NAME) then :added
+        elsif servers[SERVER_NAME] == entry then :unchanged
+        elsif @force then :updated
+        else :skipped
+        end
+
+      if %i[created added updated].include?(status) && !@dry_run
+        servers[SERVER_NAME] = entry
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(config)}\n")
+      end
+      Result.new(agent: agent, path: path, status: status)
+    end
+
+    # Returns the parsed object, {} for a missing or empty file, or an error message String.
+    def read_json(path)
+      return {} unless File.exist?(path)
+
+      text = File.read(path)
+      return {} if text.strip.empty?
+
+      parsed = JSON.parse(text)
+      parsed.is_a?(Hash) ? parsed : "not a JSON object"
+    rescue JSON::ParserError => e
+      "invalid JSON (#{e.message.lines.first.to_s.strip}); fix or remove the file and run init again"
+    end
+
+    def codex_result
+      Result.new(agent: "codex", path: File.join("~", ".codex", "config.toml"), status: :print, snippet: codex_snippet)
+    end
+
+    def toml(value)
+      JSON.generate(value.to_s)
+    end
+  end
+end

data/lib/rails_agent_kit/routes_inspector.rb

@@ -13,14 +13,17 @@ module RailsAgentKit
   # not possible (no bin/rails, boot error, timeout) it degrades gracefully:
   # it says why and returns the raw config/routes.rb so the agent can still read it.
   # A pre-generated routes dump can be supplied with `routes_file:` to skip booting.
+  # The command runs with the app's own Ruby (see RubyEnv), which is reported as `ruby` in the result.
   class RoutesInspector
     DEFAULT_TIMEOUT = 60
 
-    def initialize(root, routes_file: nil, timeout: nil, command: nil)
+    def initialize(root, routes_file: nil, timeout: nil, command: nil, ruby_env: nil)
       @root = File.expand_path(root)
       @routes_file = routes_file && File.expand_path(routes_file, @root)
       @timeout = (timeout || ENV.fetch("RAILS_AGENT_KIT_ROUTES_TIMEOUT", DEFAULT_TIMEOUT)).to_f
       @command = command
+      @ruby_env = ruby_env
+      @ruby = nil
     end
 
     def call(filter: nil)
@@ -32,7 +35,9 @@ module RailsAgentKit
       end
 
       matched = apply_filter(routes, filter)
-      { source: source, total: routes.size, count: matched.size, routes: matched }
+      result = { source: source, total: routes.size, count: matched.size }
+      result[:ruby] = @ruby.to_h if @ruby
+      result.merge(routes: matched)
     rescue RoutesUnavailable => e
       fallback(e.message)
     end
@@ -59,12 +64,15 @@ module RailsAgentKit
       bin_rails = File.join(@root, "bin", "rails")
       raise RoutesUnavailable, "No bin/rails found in #{@root}; cannot boot the app to list routes." unless File.file?(bin_rails)
 
-      [RbConfig.ruby, "bin/rails", "routes", "--expanded"]
+      @ruby = @ruby_env || RubyEnv.detect(@root)
+      raise RoutesUnavailable, RubyEnv.missing_message(@ruby) unless @ruby.found
+
+      [*@ruby.command_prefix, "bin/rails", "routes", "--expanded"]
     end
 
     def run(cmd)
       with_app_env do
-        Open3.popen3(*cmd, chdir: @root, pgroup: true) do |stdin, stdout, stderr, wait|
+        Open3.popen3(ruby_env_vars, *cmd, chdir: @root, pgroup: true) do |stdin, stdout, stderr, wait|
           stdin.close
           out_reader = reader(stdout)
           err_reader = reader(stderr)
@@ -84,6 +92,16 @@ module RailsAgentKit
       raise RoutesUnavailable, "Could not run `#{cmd.join(' ')}`: #{e.message}"
     end
 
+    # When the app uses a different Ruby than this server, put its bin first on PATH and drop the gem paths of
+    # the server's Ruby so the app's Ruby uses its own gems.
+    def ruby_env_vars
+      return {} if @ruby.nil? || @ruby.manager.nil?
+
+      bin = File.dirname(@ruby.ruby)
+      { "PATH" => [bin, ENV.fetch("PATH", nil)].compact.join(File::PATH_SEPARATOR),
+        "GEM_HOME" => nil, "GEM_PATH" => nil, "RUBYOPT" => nil, "RUBYLIB" => nil }
+    end
+
     # Run the app with its own Gemfile, not this gem's bundle.
     def with_app_env(&block)
       if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)

data/lib/rails_agent_kit/ruby_env.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "rubygems"
+
+module RailsAgentKit
+  # Works out which Ruby a Rails app wants and where to find it, without a shell profile.
+  #
+  # The required version comes from the first of `.ruby-version`, `.tool-versions`, `mise.toml` (or `.mise.toml`)
+  # and the Gemfile `ruby` directive, looked up from the app root upwards like rbenv and mise do. If the Ruby running
+  # rails-agent-kit satisfies it, that Ruby is used. Otherwise the installs of mise, rbenv, asdf and chruby are
+  # searched directly, so this also works when an editor starts the server with a minimal PATH.
+  class RubyEnv
+    Result = Struct.new(:required_version, :source_file, :manager, :ruby, :version, :found, keyword_init: true) do
+      # The command that runs a Ruby script with the app's Ruby, e.g. ["/home/me/.rbenv/versions/3.3.5/bin/ruby"].
+      def command_prefix
+        found ? [ruby] : []
+      end
+
+      def to_h
+        { version: version, required: required_version, source: source_file, manager: manager, command: ruby }.compact
+      end
+    end
+
+    VERSION_FILES = [".ruby-version", ".tool-versions", "mise.toml", ".mise.toml"].freeze
+    INSTALL_HINTS = {
+      "mise" => "mise install ruby@%s",
+      "rbenv" => "rbenv install %s",
+      "asdf" => "asdf install ruby %s",
+      "chruby" => "ruby-install ruby %s"
+    }.freeze
+
+    def self.detect(root, env: ENV)
+      new(root, env: env).detect
+    end
+
+    def initialize(root, env: ENV, current_ruby: RbConfig.ruby, current_version: RUBY_VERSION)
+      @root = File.expand_path(root)
+      @env = env
+      @current_ruby = current_ruby
+      @current_version = current_version
+    end
+
+    def detect
+      required, source = required_version
+      return current(nil, nil) if required.nil?
+      return current(required, source) if satisfies?(@current_version, required)
+
+      manager, version, ruby = find_install(required)
+      if ruby
+        Result.new(required_version: required, source_file: source, manager: manager, ruby: ruby, version: version,
+                   found: true)
+      else
+        Result.new(required_version: required, source_file: source, manager: preferred_manager(source),
+                   found: false)
+      end
+    end
+
+    # A one-line explanation for a Result that wasn't found.
+    def self.missing_message(result)
+      hint = format(INSTALL_HINTS.fetch(result.manager || "rbenv"), result.required_version.sub(/\A[~><=\s]+/, ""))
+      "The app wants Ruby #{result.required_version} (from #{result.source_file}), but it isn't installed. " \
+        "Install it with `#{hint}`, or set RAILS_AGENT_KIT_ROUTES_COMMAND."
+    end
+
+    private
+
+    def current(required, source)
+      Result.new(required_version: required, source_file: source, manager: nil, ruby: @current_ruby,
+                 version: @current_version, found: true)
+    end
+
+    # Returns [requirement, source file relative to the app root] or nil.
+    def required_version
+      dir = @root
+      loop do
+        VERSION_FILES.each do |name|
+          path = File.join(dir, name)
+          next unless File.file?(path)
+
+          version = parse_version_file(name, File.read(path))
+          return [version, relative(path)] if version
+        end
+        gemfile = File.join(dir, "Gemfile")
+        if File.file?(gemfile) && (version = parse_gemfile(File.read(gemfile)))
+          return [version, relative(gemfile)]
+        end
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+
+    def parse_version_file(name, text)
+      case name
+      when ".ruby-version"
+        normalize(text.lines.map(&:strip).find { |l| !l.empty? && !l.start_with?("#") })
+      when ".tool-versions"
+        line = text.lines.map(&:strip).find { |l| l.match?(/\Aruby\s+\S/) }
+        line && normalize(line.split[1])
+      else
+        match = text.match(/^\s*ruby\s*=\s*["']([^"']+)["']/)
+        match && normalize(match[1])
+      end
+    end
+
+    def parse_gemfile(text)
+      match = text.match(/^\s*ruby\s*\(?\s*["']([^"']+)["']/)
+      match && match[1].strip
+    end
+
+    # "ruby-3.3.5" -> "3.3.5". Non-MRI engines (jruby-9.4, truffleruby) and "system" are not handled.
+    def normalize(version)
+      return nil if version.nil?
+
+      version = version.strip.delete_prefix("ruby-")
+      version.match?(/\A\d+(\.\d+)*\z/) ? version : nil
+    end
+
+    def satisfies?(candidate, required)
+      if required.match?(/\A\s*[~><=!]/)
+        Gem::Requirement.new(*required.split(",").map(&:strip)).satisfied_by?(Gem::Version.new(candidate))
+      else
+        candidate == required || candidate.start_with?("#{required}.")
+      end
+    rescue ArgumentError
+      false
+    end
+
+    def preferred_manager(source)
+      case File.basename(source.to_s)
+      when ".tool-versions" then "asdf"
+      when "mise.toml", ".mise.toml" then "mise"
+      else installed_managers.first
+      end
+    end
+
+    def installed_managers
+      install_roots.select { |_, dirs| dirs.any? { |d| File.directory?(d) } }.map(&:first)
+    end
+
+    # manager => directories that hold one subdirectory per installed Ruby.
+    def install_roots
+      home = @env["HOME"] || Dir.home
+      {
+        "mise" => [File.join(@env["MISE_DATA_DIR"] || File.join(home, ".local/share/mise"), "installs/ruby")],
+        "rbenv" => [File.join(@env["RBENV_ROOT"] || File.join(home, ".rbenv"), "versions")],
+        "asdf" => [File.join(@env["ASDF_DATA_DIR"] || File.join(home, ".asdf"), "installs/ruby")],
+        "chruby" => [File.join(home, ".rubies"), "/opt/rubies"]
+      }
+    end
+
+    # Returns [manager, version, ruby path] for the newest install that satisfies the requirement.
+    def find_install(required)
+      candidates = install_roots.flat_map do |manager, dirs|
+        dirs.flat_map do |dir|
+          Dir.glob(File.join(dir, "*", "bin", "ruby")).filter_map do |ruby|
+            version = File.basename(File.dirname(File.dirname(ruby))).delete_prefix("ruby-")
+            next unless version.match?(/\A\d+(\.\d+)*\z/) && File.executable?(ruby) && !File.symlink?(File.dirname(File.dirname(ruby)))
+
+            [manager, version, ruby] if satisfies?(version, required)
+          end
+        end
+      end
+      candidates.max_by { |_, version, _| Gem::Version.new(version) }
+    end
+
+    def relative(path)
+      path.start_with?("#{@root}/") ? path.delete_prefix("#{@root}/") : path
+    end
+  end
+end

data/lib/rails_agent_kit/schema_inspector.rb

@@ -1,51 +1,150 @@
 # frozen_string_literal: true
 
+require "json"
+
 module RailsAgentKit
   # Reads the schema of a Rails app at `root` without booting it.
   # Prefers db/schema.rb, falls back to db/structure.sql.
+  #
+  # Agents usually call the schema tool with no arguments first, and a real app can have hundreds of tables,
+  # so the default answer is a compact overview (table names, column counts, primary keys and foreign key
+  # targets). Details come from `table:` (one name, an array, or a comma-separated list), `search:` (a
+  # case-insensitive match on table or column names) or `detail: "full"`.
   class SchemaInspector
-    def initialize(root)
+    DETAILS = %w[overview full].freeze
+
+    # Responses larger than this (serialized JSON, in bytes) are replaced by the overview plus a note on
+    # how to narrow the request, so a single call can't flood the agent's context.
+    MAX_BYTES = 60_000
+
+    OVERVIEW_HINT = "This is an overview. Pass table: \"users\" (or an array of names) for columns, indexes and " \
+                    "foreign keys, search: \"email\" to find tables and columns by name, or detail: \"full\" " \
+                    "for the whole schema."
+
+    def initialize(root, max_bytes: MAX_BYTES)
       @root = File.expand_path(root)
+      @max_bytes = max_bytes
     end
 
     # Returns a Hash with :source, :tables, ... or :error.
-    def call(table: nil)
-      schema_rb = File.join(@root, "db", "schema.rb")
-      structure_sql = File.join(@root, "db", "structure.sql")
+    #
+    # - table:  a table name, an Array of names, or "a, b". Returns those tables in full.
+    # - search: case-insensitive substring of a table or column name.
+    # - detail: "overview" or "full". Defaults to "full" when `table` or `search` is given, else "overview".
+    def call(table: nil, search: nil, detail: nil)
+      result = load_schema
+      return result if result.key?(:error)
 
-      result =
-        if File.file?(schema_rb)
-          SchemaParser.parse_file(schema_rb).to_h.merge(source: "db/schema.rb")
-        elsif File.file?(structure_sql)
-          StructureSqlParser.parse_file(structure_sql).merge(
-            source: "db/structure.sql",
-            note: "Parsed from db/structure.sql on a best-effort basis; column types are raw SQL and " \
-                  "foreign keys/constraints are not extracted. db/schema.rb gives more precise results."
-          )
-        else
-          return { error: "No db/schema.rb or db/structure.sql found under #{@root}. " \
-                          "Run `bin/rails db:schema:dump` in the app, or pass --root pointing at the Rails app." }
-        end
+      names = normalize_tables(table)
+      search = search.to_s.strip
+      detail = detail.to_s.strip.downcase
+      detail = nil if detail.empty?
+      if detail && !DETAILS.include?(detail)
+        return { error: "Unknown detail #{detail.inspect}. Use \"overview\" or \"full\"." }
+      end
 
-      filter(result, table)
+      if names.any?
+        result = select_tables(result, names)
+        return result if result.key?(:error)
+      end
+
+      return search_result(result, search) unless search.empty?
+
+      detail ||= names.any? ? "full" : "overview"
+      out = detail == "overview" ? overview(result) : result
+      guard_size(out, result)
     end
 
     private
 
-    def filter(result, table)
-      return result if table.nil? || table.to_s.strip.empty?
+    def load_schema
+      schema_rb = File.join(@root, "db", "schema.rb")
+      structure_sql = File.join(@root, "db", "structure.sql")
+
+      if File.file?(schema_rb)
+        SchemaParser.parse_file(schema_rb).to_h.merge(source: "db/schema.rb")
+      elsif File.file?(structure_sql)
+        StructureSqlParser.parse_file(structure_sql).merge(
+          source: "db/structure.sql",
+          note: "Parsed from db/structure.sql on a best-effort basis; column types are raw SQL and " \
+                "foreign keys/constraints are not extracted. db/schema.rb gives more precise results."
+        )
+      else
+        { error: "No db/schema.rb or db/structure.sql found under #{@root}. " \
+                 "Run `bin/rails db:schema:dump` in the app, or pass --root pointing at the Rails app." }
+      end
+    end
+
+    def normalize_tables(table)
+      Array(table).flat_map { |t| t.to_s.split(",") }.map(&:strip).reject(&:empty?).uniq
+    end
 
-      tables = result[:tables].select { |t| t[:name] == table.to_s }
-      if tables.empty?
-        names = result[:tables].map { |t| t[:name] }
-        return { error: "Table #{table.inspect} not found in #{result[:source]}.", available_tables: names }
+    def select_tables(result, names)
+      known = result[:tables].map { |t| t[:name] }
+      missing = names - known
+      if missing.size == names.size
+        label = names.size == 1 ? "Table #{names.first.inspect}" : "Tables #{names.map(&:inspect).join(', ')}"
+        return { error: "#{label} not found in #{result[:source]}.", available_tables: known }
       end
 
-      out = result.merge(tables: tables)
+      out = result.merge(tables: result[:tables].select { |t| names.include?(t[:name]) })
       if out.key?(:foreign_keys)
-        out[:foreign_keys] = out[:foreign_keys].select { |fk| fk[:from_table] == table.to_s || fk[:to_table] == table.to_s }
+        out[:foreign_keys] = out[:foreign_keys].select do |fk|
+          names.include?(fk[:from_table]) || names.include?(fk[:to_table])
+        end
       end
+      out[:missing_tables] = missing if missing.any?
       out
     end
+
+    def overview(result)
+      fks = Array(result[:foreign_keys]).group_by { |fk| fk[:from_table] }
+      tables = result[:tables].map do |t|
+        entry = { name: t[:name], columns: t[:columns].size }
+        entry[:primary_key] = t[:primary_key] || false if t.key?(:primary_key) && t[:primary_key] != "id"
+        refs = Array(fks[t[:name]]).map { |fk| fk[:to_table] }.uniq
+        entry[:references] = refs if refs.any?
+        entry
+      end
+      meta(result).merge(detail: "overview", table_count: tables.size, hint: OVERVIEW_HINT, tables: tables)
+    end
+
+    def search_result(result, search)
+      needle = search.downcase
+      matches = result[:tables].filter_map do |t|
+        table_match = t[:name].downcase.include?(needle)
+        columns = t[:columns].select { |c| c[:name].downcase.include?(needle) }
+        next unless table_match || columns.any?
+
+        entry = { table: t[:name] }
+        entry[:table_name_match] = true if table_match
+        entry[:columns] = columns.map { |c| c.slice(:name, :type, :null, :primary_key).compact }
+        entry[:column_names] = t[:columns].map { |c| c[:name] } if table_match
+        entry
+      end
+      out = meta(result).merge(search: search, match_count: matches.size, matches: matches)
+      if matches.empty?
+        out[:hint] = "No table or column name contains #{search.inspect}. Call rails_schema without arguments " \
+                     "for the list of tables."
+      end
+      out[:missing_tables] = result[:missing_tables] if result[:missing_tables]
+      guard_size(out, result)
+    end
+
+    def meta(result)
+      result.slice(:source, :version, :note)
+    end
+
+    def guard_size(out, result)
+      size = JSON.generate(out).bytesize
+      return out if size <= @max_bytes || out[:detail] == "overview"
+
+      overview(result).merge(
+        truncated: true,
+        message: "The full answer is #{size / 1024} KB, over the #{@max_bytes / 1024} KB limit, so this is the " \
+                 "overview instead. Narrow the request: pass table: with one or a few table names, or search: " \
+                 "with part of a table or column name."
+      )
+    end
   end
 end

data/lib/rails_agent_kit/server.rb

@@ -13,8 +13,11 @@ module RailsAgentKit
       MCP::Server.new(
         name: "rails-agent-kit",
         version: RailsAgentKit::VERSION,
-        instructions: "Ground truth about the Rails app at #{context[:root]}: use rails_schema for tables/columns/indexes " \
-                      "and rails_routes for HTTP routes before guessing model attributes or URL helpers.",
+        instructions: "Ground truth about the Rails app at #{context[:root]}. Check it before guessing model " \
+                      "attributes or URL helpers. rails_schema with no arguments lists every table (column counts " \
+                      "and foreign key targets); then pass table: (one name or an array) for columns, indexes " \
+                      "and foreign keys, or search: to find a column by name. rails_routes lists HTTP routes; " \
+                      "pass filter: to narrow them.",
         tools: [Tools::RailsSchema, Tools::RailsRoutes],
         server_context: context
       )
@@ -34,7 +37,7 @@ module RailsAgentKit
       end
 
       def json_response(data, error: false)
-        MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(data) }], error: error)
+        MCP::Tool::Response.new([{ type: "text", text: JSON.generate(data) }], error: error)
       end
     end
 
@@ -42,18 +45,31 @@ module RailsAgentKit
       extend Helpers
 
       tool_name "rails_schema"
-      description "Database schema of the Rails app (tables, columns with types/null/default, indexes, foreign keys), " \
-                  "parsed from db/schema.rb (or db/structure.sql) without booting the app."
+      description "Database schema of the Rails app, parsed from db/schema.rb (or db/structure.sql) without booting " \
+                  "the app. With no arguments it returns a compact overview: every table with its column count, " \
+                  "non-default primary key and foreign key targets. Pass table for full columns (type, null, " \
+                  "default, ...), indexes and foreign keys, or search to find tables and columns by name."
       input_schema(
         properties: {
-          table: { type: "string", description: "Only return this table (exact name). Omit for all tables." }
+          table: {
+            anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+            description: "Table name(s) to return in full: one exact name, an array, or a comma-separated list."
+          },
+          search: {
+            type: "string",
+            description: "Case-insensitive substring matched against table and column names, e.g. \"email\"."
+          },
+          detail: {
+            type: "string", enum: SchemaInspector::DETAILS,
+            description: "\"overview\" (default with no table/search) or \"full\" (default with table)."
+          }
         }
       )
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
-      def self.call(server_context:, table: nil)
+      def self.call(server_context:, table: nil, search: nil, detail: nil)
         root = context_value(server_context, :root) || Dir.pwd
-        result = SchemaInspector.new(root).call(table: table)
+        result = SchemaInspector.new(root).call(table: table, search: search, detail: detail)
         json_response(result, error: result.key?(:error))
       end
     end