rails-ai-context 5.35.0 → 5.35.2

data/lib/rails_ai_context/tools/read_logs.rb

@@ -34,7 +34,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 33,
+        order: 28,
         mcp: "rails_read_logs(level:\"X\")",
         cli_args: "level=X",
         summary: "Reverse file tail with level filtering and sensitive data redaction"

data/lib/rails_ai_context/tools/review_changes.rb

@@ -27,7 +27,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 36,
+        order: 31,
         mcp: "rails_review_changes(ref:\"main\")",
         cli_args: "ref=main",
         summary: "PR/commit review: file context + warnings (missing indexes, removed validations)"
@@ -150,12 +150,11 @@ module RailsAiContext
         rb_files = classified.select { |c| c[:file].end_with?(".rb") }.map { |c| c[:file] }
         if rb_files.any?
           file_list = rb_files.first(10).map { |f| "\"#{f}\"" }.join(", ")
-          lines << "_Next: `rails_validate(files:[#{file_list}], level:\"rails\")` to validate all changes._"
+          hint = next_hint(pointer("rails_validate", %(files:[#{file_list}], level:"rails"), "to validate all changes."))
+          lines << hint if hint
         end
 
         text_response(lines.join("\n"))
-      rescue => e
-        text_response("Review error: #{e.message}")
       end
 
       class << self
@@ -286,7 +285,7 @@ module RailsAiContext
           when :model
             model_name = File.basename(file, ".rb").camelize
             begin
-              result = GetModelDetails.call(model: model_name, detail: "standard")
+              result = compose(GetModelDetails, model: model_name, detail: "standard")
               lines << "" << "**Model context:** #{model_name}" unless empty?(result)
             rescue => e; RailsAiContext.debug_fail(e, nil, label: "review_changes context lookup"); end
 
@@ -294,7 +293,7 @@ module RailsAiContext
             ctrl_name = File.basename(file, ".rb").camelize
             snake = ctrl_name.underscore.delete_suffix("_controller")
             begin
-              result = GetRoutes.call(controller: snake, detail: "summary")
+              result = compose(GetRoutes, controller: snake, detail: "summary")
               lines << "" << "**Routes:**" << response_text(result) unless empty?(result)
             rescue => e; RailsAiContext.debug_fail(e, nil, label: "review_changes context lookup"); end
 
@@ -324,7 +323,7 @@ module RailsAiContext
 
           when :routes
             begin
-              result = GetRoutes.call(detail: "summary")
+              result = compose(GetRoutes, detail: "summary")
               summary = response_text(result).lines.first&.strip&.sub(/\A#+\s*/, "")
               lines << "" << "**Current routes:** #{summary}" unless summary.to_s.empty?
             rescue => e; RailsAiContext.debug_fail(e, nil, label: "review_changes context lookup"); end

data/lib/rails_ai_context/tools/runtime_info.rb

@@ -15,12 +15,16 @@ module RailsAiContext
             type: "string",
             enum: %w[database cache jobs connections],
             description: "Filter to one section. Omit for all sections."
+          },
+          database: {
+            type: "string",
+            description: "The app database whose table sizes and index usage to show, by its config/database.yml name. Default: the primary."
           }
         }
       )
 
       guide_row(
-        order: 38,
+        order: 33,
         mcp: "rails_runtime_info(detail:\"standard\")",
         cli_args: "detail=standard",
         summary: "Live runtime: DB pool, table sizes, cache stats, job queues, pending migrations"
@@ -28,19 +32,21 @@ module RailsAiContext
 
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: false, open_world_hint: false)
 
-      def self.call(detail: "standard", section: nil, server_context: nil)
+      def self.call(detail: "standard", section: nil, database: nil, server_context: nil)
         if (refusal = static_tier_refusal("Live runtime state"))
           return refusal
         end
+        named = !database.to_s.empty?
+        sections = section ? [ section ] : %w[connections database cache jobs]
+        # The database section leases the named database itself, and refuses one it cannot reach.
+        AppDatabases.lease(rails_app.root, database) { nil } if named && !sections.include?("database")
 
         lines = [ "# Runtime Info", "" ]
 
-        sections = section ? [ section ] : %w[connections database cache jobs]
-
         sections.each do |s|
           result = case s
           when "connections" then gather_connection_pool
-          when "database"    then gather_database(detail)
+          when "database"    then gather_database(detail, database)
           when "cache"       then gather_cache
           when "jobs"        then gather_jobs(detail)
           end
@@ -48,12 +54,15 @@ module RailsAiContext
         end
 
         if lines.size <= 2
-          lines << "_No runtime data available. Ensure the app has a database connection._"
+          lines << "_No runtime data available: no section had anything to show._"
+        end
+        if section && section != "database" && named
+          lines << "_The #{section} section does not read `database`, so #{database} was not used._"
         end
 
         text_response(lines.join("\n"))
-      rescue => e
-        text_response("Runtime info error: #{e.message}")
+      rescue AppDatabases::Error => e
+        error_response(e.message)
       end
 
       class << self
@@ -91,17 +100,32 @@ module RailsAiContext
 
         # ── Database section ─────────────────────────────────────────────
 
-        def gather_database(detail)
+        def gather_database(detail, database)
           return [ "## Database", "", "_ActiveRecord not available._", "" ] unless defined?(ActiveRecord::Base)
 
-          conn = ActiveRecord::Base.connection
-          adapter = conn.adapter_name.downcase
-          lines = [ "## Database", "" ]
+          AppDatabases.lease(rails_app.root, database) { |conn| database_lines(conn, detail, database) }
+        rescue AppDatabases::Missing, AppDatabases::Unreachable => e
+          raise unless database.to_s.empty?
+
+          [ "## Database", "", "_Not available: #{e.message}_", "" ]
+        rescue AppDatabases::Error
+          raise
+        rescue => e
+          [ "## Database", "", "_Not available: #{e.message}_", "" ]
+        end
+
+        def database_lines(conn, detail, database)
+          family = DatabaseFamily.of(conn)
+          lines = [ database.to_s.empty? ? "## Database" : "## Database: #{database}", "" ]
           lines << "**Adapter:** #{SchemaAdapter.display(conn.adapter_name)}"
+          unless family.known?
+            lines << "" << "_Table sizes and index usage are not available for the #{family.name} adapter._"
+          end
 
-          # Table sizes
-          sizes = gather_table_sizes(conn, adapter)
-          if sizes&.any?
+          sizes = gather_table_sizes(conn, family)
+          if sizes == :unread
+            lines << "" << "_Table sizes were not read: the read failed or took longer than query_timeout._"
+          elsif sizes&.any?
             lines << "" << "### Table Sizes"
             lines << "| Table | Size |"
             lines << "|-------|------|"
@@ -114,21 +138,16 @@ module RailsAiContext
             lines << "_#{count_phrase(sizes.size - shown, "more table")}..._" if sizes.size > shown
           end
 
-          # Pending migrations
-          pending = gather_pending_migrations
-          if pending
-            if pending.empty?
-              lines << "" << "**Migrations:** all up to date"
-            else
-              lines << "" << "**Pending migrations:** #{pending.size}"
-              pending.each { |m| lines << "- #{m[:version]} #{m[:name]}" }
-            end
-          end
+          lines.concat(database.to_s.empty? ? pending_migration_lines : own_pending_migration_lines(conn, database))
 
           # Index usage (full detail only)
           if RailsAiContext::DetailLevel.full?(detail)
-            index_usage = gather_index_usage(conn, adapter)
-            if index_usage&.any?
+            index_usage = gather_index_usage(conn, family)
+            if index_usage == :unread
+              lines << "" << "_Index usage was not read: the read failed or took longer than query_timeout._"
+            elsif index_usage.nil? && family.known?
+              lines << "" << "_Index usage is not available for the #{family.name} database family._"
+            elsif index_usage&.any?
               lines << "" << "### Index Usage"
               unused = index_usage.select { |i| i[:scans] == 0 }
               if unused.any?
@@ -144,8 +163,6 @@ module RailsAiContext
 
           lines << ""
           lines
-        rescue => e
-          [ "## Database", "", "_Not available: #{e.message}_", "" ]
         end
 
         # Rails-managed bookkeeping tables - real tables, but noise in a
@@ -153,72 +170,76 @@ module RailsAiContext
         # introspector, which also skips them).
         INTERNAL_TABLES = %w[schema_migrations ar_internal_metadata].freeze
 
-        # Trilogy is Rails 8's default MySQL adapter (`adapter_name` reports
-        # "Trilogy", not "Mysql2") - matching only /mysql/ silently drops
-        # table sizes for every Trilogy app.
-        MYSQL_ADAPTER = /mysql|trilogy/i
-
-        # activerecord-postgis-adapter reports "PostGIS" for what is a PostgreSQL connection.
-        POSTGRES_ADAPTER = /postg/i
-
-        def gather_table_sizes(conn, adapter)
-          rows =
-            case adapter
-            when POSTGRES_ADAPTER
-              Introspectors::PgPartitions.table_bytes(conn).sort_by { |r| [ -r[:bytes], r[:name] ] }
-            when MYSQL_ADAPTER
-              sql = "SELECT table_name AS name, (data_length + index_length) AS bytes FROM INFORMATION_SCHEMA.TABLES WHERE table_schema = DATABASE() ORDER BY bytes DESC"
-              conn.select_all(sql).map { |r| { name: r["name"], bytes: r["bytes"].to_i } }
-            when /sqlite/
-              gather_sqlite_table_sizes(conn)
-            end
-          return nil unless rows
+        def gather_table_sizes(conn, family)
+          return nil unless family.known?
 
-          rows.reject { |r| INTERNAL_TABLES.include?(r[:name]) }
+          AppDatabases.bounded(conn) { family.table_sizes(conn) }&.reject { |r| INTERNAL_TABLES.include?(r[:name]) }
         rescue => e
-          RailsAiContext.debug_fail(e, nil, label: "gather_table_sizes")
+          RailsAiContext.debug_fail(e, :unread, label: "gather_table_sizes")
         end
 
-        def gather_sqlite_table_sizes(conn)
-          # dbstat lists every b-tree: user tables, their indexes, and SQLite
-          # internals (sqlite_schema, sqlite_autoindex_*, sqlite_sequence).
-          # Restrict to real application tables so indexes and internal objects
-          # don't crowd out (or get mistaken for) the tables agents care about.
-          app_tables = conn.select_values(
-            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
-          ).to_set
-
-          begin
-            result = conn.select_all("SELECT name, SUM(pgsize) AS bytes FROM dbstat GROUP BY name ORDER BY bytes DESC")
-            rows = result.filter_map do |r|
-              { name: r["name"], bytes: r["bytes"].to_i } if app_tables.include?(r["name"])
-            end
-            return rows if rows.any?
+        # Every database Rails migrates here, each through its own connection.
+        def pending_migration_lines
+          here = AppDatabases.for(rails_app.root).here
+          primary = here.find(&:primary)
+          migrated = here.select(&:tasks)
+          return primary_pending_lines if primary.nil? || migrated == [ primary ]
+          return no_migrations_line(primary) if migrated.empty?
+
+          states = migrated.to_h { |db| [ db, db.pending_migrations ] }.reject { |_, state| state[:error].is_a?(AppDatabases::InMemory) }
+          read, unread = states.partition { |_, state| state[:pending] }
+          lines = pending_lines(read.to_h { |db, state| [ db.name, state[:pending] ] }, named: true)
+          unread.each { |db, state| lines << "" << "_Pending migrations could not be read for #{db.name}: #{state[:error].message.lines.first.to_s.strip}_" }
+          lines
+        end
+
+        # The app's one migrated database, read through the app's own connection.
+        def primary_pending_lines
+          dirs = RailsAiContext::PendingMigrations.migrate_dirs_for(rails_app.root)
+          pending = begin
+            AppDatabases.bounded(ActiveRecord::Base.connection) { RailsAiContext::PendingMigrations.live(dirs) }
           rescue => e
-            RailsAiContext.debug_fail(e, label: "gather_sqlite_table_sizes (dbstat)")
+            RailsAiContext.debug_fail(e, nil, label: "primary_pending_lines")
           end
-
-          # Fallback: whole-DB size split across user tables (dbstat unavailable).
-          page_count = conn.select_value("PRAGMA page_count").to_i
-          page_size = conn.select_value("PRAGMA page_size").to_i
-          total = page_count * page_size
-          tables = app_tables.to_a.sort
-          tables.map { |t| { name: t, bytes: total / [ tables.size, 1 ].max } }
+          pending ? pending_lines({ "primary" => pending }) : []
         end
 
-        def gather_pending_migrations
-          RailsAiContext::PendingMigrations.live(RailsAiContext::PendingMigrations.migrate_dirs_for(rails_app.root))
+        # A named database's own, read through the connection the section leased.
+        def own_pending_migration_lines(conn, name)
+          db = AppDatabases.for(rails_app.root).fetch(name)
+          return no_migrations_line(db) unless db.tasks
+
+          dirs = db.primary ? RailsAiContext::PendingMigrations.migrate_dirs_for(rails_app.root) : db.migrate_dirs
+          pending_lines({ db.name => AppDatabases.bounded(conn) { RailsAiContext::MigrationStatus.pending_on(conn.pool, dirs) } })
+        rescue AppDatabases::Error
+          raise
+        rescue => e
+          [ "", "_Pending migrations could not be read for #{name}: #{e.message.lines.first.to_s.strip}_" ]
         end
 
-        def gather_index_usage(conn, adapter)
-          case adapter
-          when POSTGRES_ADAPTER
-            Introspectors::PgPartitions.index_stats(conn).sort_by { |i| [ i[:scans], i[:table], i[:index] ] }
-          else
-            nil
+        # found: each database that was read, by name, with its pending migrations. named: says which database each is in.
+        def pending_lines(found, named: false)
+          return [] if found.empty?
+
+          pending = found.flat_map { |name, list| list.map { |m| "- #{m[:version]} #{m[:name]}#{" (#{name})" if named}" } }
+          return [ "", "**Migrations:** all up to date#{" in #{found.keys.join(', ')}" if named}" ] if pending.empty?
+
+          counts = found.reject { |_, list| list.empty? }.map { |name, list| "#{list.size} in #{name}" }
+          total = if !named then pending.size
+          else counts.one? ? counts.first : "#{pending.size} (#{counts.join(', ')})"
           end
+          [ "", "**Pending migrations:** #{total}", *pending ]
+        end
+
+        def no_migrations_line(db)
+          reason = db.replica ? "it is a replica" : "its database.yml entry turns `database_tasks` off"
+          [ "", "_Rails runs no migrations on #{db.name}: #{reason}._" ]
+        end
+
+        def gather_index_usage(conn, family)
+          AppDatabases.bounded(conn) { family.index_usage(conn) } if family.known?
         rescue => e
-          RailsAiContext.debug_fail(e, nil, label: "gather_index_usage")
+          RailsAiContext.debug_fail(e, :unread, label: "gather_index_usage")
         end
 
         # ── Cache section ────────────────────────────────────────────────
@@ -271,17 +292,33 @@ module RailsAiContext
             store = (env[:notable] || {})["cache_store"]
             next unless store && !store.match?(PROCESS_STORES)
 
-            # The store's name; its options are rails_get_env_config's to show, unshortened.
+            # The store's name; its options are the env_config section's to show, unshortened.
             "- #{env[:name]}: `#{store[/\A:\w+/] || store}` (`#{env[:file]}`)"
           end
         end
 
+        # Solid Cache answers #stats from its databases, one per shard, and
+        # connecting to a SQLite file that is not there creates it.
+        def cache_database_missing(cache)
+          return unless defined?(::SolidCache::Store) && cache.is_a?(::SolidCache::Store)
+
+          cache.with_each_connection do
+            config = ::SolidCache::Record.connection_db_config
+            AppDatabases.present!(config.name, config)
+          end
+          nil
+        rescue AppDatabases::Missing, AppDatabases::Unreachable => e
+          e.message
+        end
+
         def gather_cache
           cache = Rails.cache
           lines = [ "## Cache", "" ]
-          lines << "**Store:** #{cache.class.name.demodulize}, this MCP server process's `Rails.cache` (#{rails_env_name})"
+          lines << "**Store:** #{cache.class.name.delete_prefix("ActiveSupport::Cache::")}, this MCP server process's `Rails.cache` (#{rails_env_name})"
 
-          if cache.respond_to?(:stats)
+          if (missing = cache_database_missing(cache))
+            lines << "_#{missing}_"
+          elsif cache.respond_to?(:stats)
             cache_stat_lines(cache.stats).each { |line| lines << line }
           elsif cache.respond_to?(:redis)
             begin
@@ -309,8 +346,8 @@ module RailsAiContext
           lines << "" << cache_scope(cache)
           elsewhere = configured_elsewhere
           if elsewhere.any?
-            lines.push("", "**The app's cache in other environments:**", *elsewhere,
-                       "_`rails_get_env_config(environment:\"...\")` shows each one's options._")
+            options = pointer("rails_get_env_config", %(environment:"..."), "shows each one's options.")
+            lines.push("", "**The app's cache in other environments:**", *elsewhere, *("_#{options}_" if options))
           end
 
           lines << ""

data/lib/rails_ai_context/tools/safe_call.rb

@@ -13,6 +13,22 @@ module RailsAiContext
     # model's context instead, with enough detail to retry or route around
     # the failure.
     module SafeCall
+      # The content with the note ending its first text block, or the content
+      # itself when there is no note or no text to end.
+      def self.noted(content, note)
+        first = Array(content).first
+        return content unless note && first.is_a?(Hash) && first[:type] == "text"
+
+        body = first[:text].to_s
+        [ first.merge(text: body.strip.empty? ? note.lstrip : "#{body}#{note}") ] + content[1..].to_a
+      end
+
+      # The parameters tools/list shows, which for rails_get_config leaves out those of a section turned off.
+      def self.published_params(tool)
+        schema = tool.respond_to?(:input_schema_value) ? tool.input_schema_value : tool.input_schema
+        (schema&.to_h&.dig(:properties) || {}).keys.map(&:to_s)
+      end
+
       def call(**kwargs)
         # An MCP client sends whatever keys it likes. Reaching the tool with
         # one it does not declare answers with an unknown-keyword ArgumentError
@@ -27,10 +43,6 @@ module RailsAiContext
         # have its note consumed by the inner one.
         discarded = discarded_detail(kwargs)
         kwargs = listify_arrays(normalize_detail(kwargs))
-        # Before the call reads anything: an edit since the last call drops
-        # the caches and reloads the app's code (see the method).
-        RailsAiContext::Tools::BaseTool.refresh_if_files_changed!
-
         answer = -> { answer_call(discarded) { super(**kwargs) } }
 
         # Only the call the client made is its query. A composite tool answers
@@ -39,14 +51,27 @@ module RailsAiContext
         # first inner call took the outer one's params with it.
         return answer.call if Thread.current[:rails_ai_context_call]
 
-        Thread.current[:rails_ai_context_call] = { tool: self, params: session_params(kwargs) }
+        # Before the call reads anything: an edit since the last call drops
+        # the caches and reloads the app's code (see the method).
+        RailsAiContext::Tools::BaseTool.refresh_if_files_changed!
+        call = Thread.current[:rails_ai_context_call] = { tool: self, params: session_params(kwargs) }
         begin
-          answer.call
+          with_crashes(answer.call, call[:crashed])
         ensure
           Thread.current[:rails_ai_context_call] = nil
         end
       end
 
+      def unknown_param_response(unknown, known = SafeCall.published_params(self))
+        lines = unknown.map do |name|
+          suggestion = RailsAiContext::Tools::BaseTool.find_closest_match(name, known)
+          suggestion ? "'#{name}' - did you mean '#{suggestion}'?" : "'#{name}'"
+        end
+        valid = known.any? ? "Valid params: #{known.join(', ')}" : "This tool takes no params."
+        text = "Unknown param#{"s" if unknown.size > 1}: #{lines.join(', ')}\n#{valid}"
+        MCP::Tool::Response.new([ { type: "text", text: text } ], error: true)
+      end
+
       private
 
       def answer_call(discarded)
@@ -61,16 +86,40 @@ module RailsAiContext
         RailsAiContext::CodeReloader.with_app_code do
           begin
             # One call is one run: what it reads per controller or per route is read once.
-            append_note(RailsAiContext::RunCache.around { yield }, invalid_detail_note(discarded))
-          # ScriptError too: a SyntaxError or LoadError out of an app file the
-          # tool reached must cost that call, not the stdio server and every
-          # tool with it.
-          rescue StandardError, ScriptError => e
-            failure_response(e)
+            response, left_out = with_left_out_frame { RailsAiContext::RunCache.around { yield } }
+            response = append_note(response, RailsAiContext::Tools::BaseTool.left_out_note(left_out))
+            append_note(response, invalid_detail_note(discarded))
+          # An app file that cannot load, a stack overflow or a SecurityError costs that call,
+          # where a StandardError rescue alone would let it end the stdio server and every tool with it.
+          rescue StandardError, ScriptError, SystemStackError, SecurityError => e
+            failure_response(e).tap do |failure|
+              call = Thread.current[:rails_ai_context_call]
+              (call[:crashed] ||= []) << failure.content.first[:text] if call
+            end
           end
         end
       end
 
+      # A tool this call ran crashed: the answer is an error, and it says so where its text left the crash out.
+      def with_crashes(response, crashes)
+        return response unless crashes && response.respond_to?(:error?) && !response.error?
+
+        text = response.content.first&.dig(:text).to_s
+        unsaid = crashes.uniq.reject { |failure| text.include?(failure.lines.first.strip) }
+        rebuilt(response, SafeCall.noted(response.content, ("\n\n#{unsaid.join("\n\n")}" if unsaid.any?)), error: true)
+      end
+
+      # The tools this call's composed sections left out, kept apart from
+      # those of any tool it calls.
+      def with_left_out_frame
+        stack = (Thread.current[RailsAiContext::Tools::BaseTool::LEFT_OUT] ||= [])
+        stack.push([])
+        response = yield
+        [ response, stack.last.uniq ]
+      ensure
+        stack.pop
+      end
+
       # The declared params are the contract, so a tool whose method takes
       # **kwargs refuses the same keys as one that names them.
       def unknown_params(kwargs)
@@ -80,17 +129,6 @@ module RailsAiContext
         RailsAiContext::Tools::BaseTool.unknown_param_names(kwargs.keys, properties)
       end
 
-      def unknown_param_response(unknown)
-        known = (input_schema.to_h[:properties] || {}).keys.map(&:to_s)
-        lines = unknown.map do |name|
-          suggestion = RailsAiContext::Tools::BaseTool.find_closest_match(name, known)
-          suggestion ? "'#{name}' - did you mean '#{suggestion}'?" : "'#{name}'"
-        end
-        valid = known.any? ? "Valid params: #{known.join(', ')}" : "This tool takes no params."
-        text = "Unknown param#{"s" if unknown.size > 1}: #{lines.join(', ')}\n#{valid}"
-        MCP::Tool::Response.new([ { type: "text", text: text } ], error: true)
-      end
-
       # A string where the schema declares an array is a list of one, and a
       # comma-separated one is the list the CLI documents (`a.rb,b.rb`): an MCP
       # client can send either, and review_changes answered a string with
@@ -108,6 +146,9 @@ module RailsAiContext
 
       def failure_response(error)
         label = respond_to?(:tool_name) ? tool_name : name
+        # A section renderer answers inside rails_get_config, the tool the caller named.
+        section = RailsAiContext::Tools::GetConfig.retired_section(label)
+        label = "rails_get_config (section #{section.name})" if section && section.renderer.equal?(self)
         origin = portable_origin(Array(error.backtrace).first.to_s)
         text = +"Tool #{label} failed: #{error.class}: #{error.message.to_s.lines.first&.strip}\n"
         text << "At: #{origin}\n" unless origin.empty?
@@ -161,12 +202,13 @@ module RailsAiContext
       def append_note(response, note)
         return response unless note && response.respond_to?(:content)
 
-        content = response.content
-        first = content.first
-        return response unless first.is_a?(Hash) && first[:type] == "text"
+        noted = SafeCall.noted(response.content, note)
+        return response if noted.equal?(response.content)
 
-        noted = [ first.merge(text: "#{first[:text]}#{note}") ] + content[1..].to_a
+        rebuilt(response, noted, error: response.error?)
+      end
 
+      def rebuilt(response, content, error:)
         # `meta` arrived in mcp 0.13, which is the gemspec floor, but the
         # reader is still asked for rather than assumed: getting it wrong
         # turns a good answer into a NoMethodError that SafeCall's own rescue
@@ -174,7 +216,7 @@ module RailsAiContext
         extra = { structured_content: response.structured_content }
         extra[:meta] = response.meta if response.respond_to?(:meta)
 
-        MCP::Tool::Response.new(noted, error: response.error?, **extra)
+        MCP::Tool::Response.new(content, error: error, **extra)
       end
     end
   end

data/lib/rails_ai_context/tools/search_code.rb

@@ -395,8 +395,6 @@ module RailsAiContext
           .reject { |r| sensitive_file?(r[:file]) || sensitive_in_tree?(r[:file], trees, root) }
           .first(max_results)
         [ rows, failed ]
-      rescue => e
-        [ [ { file: "error", line_number: 0, content: e.message } ], false ]
       end
 
       # rg opens sensitive files too, and one it cannot read is not an error
@@ -862,8 +860,6 @@ module RailsAiContext
         return definition_missing_response(lines.join("\n")) if def_results.empty?
 
         text_response(lines.join("\n"))
-      rescue => e
-        text_response("Trace error: #{e.message}")
       end
 
       SCOPE_WRAPPERS = %w[scope lambda proc].freeze

data/lib/rails_ai_context/tools/search_docs.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "json"
 require "net/http"
 require "uri"
 
@@ -37,7 +39,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 31,
+        order: 26,
         mcp: "rails_search_docs(query:\"X\")",
         cli_args: "query=X",
         summary: "Bundled topic index with weighted keyword search, on-demand GitHub fetch"

data/lib/rails_ai_context/tools/security_scan.rb

@@ -36,7 +36,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 24,
+        order: 21,
         mcp: "rails_security_scan",
         summary: "Brakeman static analysis: SQL injection, XSS, mass assignment"
       )
@@ -94,8 +94,12 @@ module RailsAiContext
           # can still answer - from outside the bundle, which is where it is.
           unbundled_scan(min_confidence, resolved_checks)
         end
-        return text_response(unavailable_message(scan&.dig(:unavailable))) if scan.nil? || scan.key?(:unavailable)
-        return text_response("Brakeman scan failed: #{portable_error(scan[:error])}") if scan[:error]
+        if scan.nil? || scan.key?(:unavailable)
+          # A run that said why it failed did start; one that could not start is brakeman not being there.
+          message = unavailable_message(scan&.dig(:unavailable))
+          return scan&.dig(:unavailable) ? error_response(message) : text_response(message)
+        end
+        return error_response("Brakeman scan failed: #{portable_error(scan[:error])}") if scan[:error]
 
         warnings = scan[:warnings]
         checks_run = scan[:checks_run]
@@ -147,7 +151,7 @@ module RailsAiContext
 
         report, failure = run_brakeman_unbundled(min_confidence, resolved_checks)
         unless report.is_a?(Hash) && report["warnings"].is_a?(Array)
-          failure = echo_checks(failure, resolved_checks)
+          failure = echo_checks(report.nil? ? failure : "its report could not be read", resolved_checks)
           # A check name brakeman does not know is the caller's to fix, and
           # is answered as the in-process scan answers it: the Gemfile advice
           # an unavailable scan gets would send them to change nothing wrong.
@@ -311,7 +315,7 @@ module RailsAiContext
 
           _out, err = with_unbundled_env { capture_with_timeout(command) }
           next [ nil, "no report after #{SCAN_TIMEOUT} seconds" ] if err.nil?
-          next [ nil, brakeman_error_line(err) ] unless File.file?(report_path) && File.size?(report_path)
+          next [ nil, brakeman_error_line(err) || "it wrote no report and printed nothing" ] unless File.file?(report_path) && File.size?(report_path)
 
           [ JSON.parse(File.read(report_path)), nil ]
         end