rails-ai-context 5.35.0 → 5.35.2

data/lib/rails_ai_context/tools/get_context.rb

@@ -4,6 +4,23 @@ module RailsAiContext
   module Tools
     class GetContext < BaseTool
       tool_name "rails_get_context"
+
+      # Each include key and the call it bundles, run only when the app serves that tool.
+      INCLUDE_MAP = {
+        "stimulus"    => [ "rails_get_stimulus", { detail: "standard" } ],
+        "turbo"       => [ "rails_get_turbo_map", { detail: "standard" } ],
+        "services"    => [ "rails_get_service_pattern", { detail: "standard" } ],
+        "jobs"        => [ "rails_get_job_pattern", { detail: "standard" } ],
+        "conventions" => [ "rails_get_config", { section: "conventions" } ],
+        "helpers"     => [ "rails_get_helper_methods", { detail: "standard" } ],
+        "env"         => [ "rails_get_config", { section: "env", detail: "summary" } ],
+        "callbacks"   => [ "rails_get_callbacks", { detail: "standard" } ],
+        "tests"       => [ "rails_get_test_info", { detail: "full" } ],
+        "config"      => [ "rails_get_config", { section: "app" } ],
+        "gems"        => [ "rails_get_config", { section: "gems" } ],
+        "security"    => [ "rails_security_scan", { detail: "summary" } ]
+      }.freeze
+
       description "Get cross-layer context in a single call - combines schema, model, controller, routes, views, stimulus, and tests. " \
         "Use when: you need full context for implementing a feature or modifying an action. " \
         "Specify controller:\"PostsController\" action:\"create\" to get everything for that action in one call."
@@ -29,7 +46,7 @@ module RailsAiContext
           include: {
             type: "array",
             items: { type: "string" },
-            description: "Additional context to bundle: 'stimulus', 'turbo', 'services', 'jobs', 'conventions', 'helpers', 'env', 'callbacks'. Appends these to any mode."
+            description: "Additional context to bundle: #{INCLUDE_MAP.keys.map { |key| "'#{key}'" }.join(', ')}. Appends these to any mode."
           }
         }
       )
@@ -56,8 +73,7 @@ module RailsAiContext
           return error_response("Provide at least one of: controller, model, or feature.")
         end
 
-        # Append additional context sections if include: is specified
-        base_text += append_includes(include) if include.is_a?(Array) && include.any?
+        base_text = sections(base_text, *include_sections(include)) if include.is_a?(Array) && include.any?
 
         ctx = begin
           cached_context
@@ -68,31 +84,26 @@ module RailsAiContext
         text_response(base_text, suffix: introspection_warnings_note(ctx))
       end
 
-      private_class_method def self.controller_action_context(controller_name, action_name)
-        lines = []
+      # The sections that have text, with a rule between them.
+      private_class_method def self.sections(*texts)
+        texts.compact.reject(&:empty?).join("\n\n---\n\n")
+      end
 
+      private_class_method def self.section_text(response)
+        response_text(response) unless empty?(response)
+      end
+
+      private_class_method def self.controller_action_context(controller_name, action_name)
         # Controller + action source + private methods + instance vars
-        ctrl_result = GetControllers.call(controller: controller_name, action: action_name)
-        lines << response_text(ctrl_result)
+        ctrl_text = controller_text(compose(GetControllers, controller: controller_name, action: action_name), controller_name, action_name)
 
         # Infer model from controller
         snake = RailsAiContext::Payload.controller_route_key(cached_context, controller_name)
         model_name = snake.split("/").last.singularize.camelize
 
-        # Model details
-        model_result = GetModelDetails.call(model: model_name)
-        unless empty?(model_result)
-          lines << "" << "---" << "" << response_text(model_result)
-        end
-
-        # Routes for this controller
-        route_result = GetRoutes.call(controller: snake)
-        unless empty?(route_result)
-          lines << "" << "---" << ""
-          lines << response_text(route_result)
-        end
-
-        lines.concat(view_section_lines(snake))
+        text = sections(ctrl_text, section_text(compose(GetModelDetails, model: model_name)),
+                        section_text(compose(GetRoutes, controller: snake)), view_section(snake))
+        extras = []
 
         # Cross-reference: controller ivars vs view ivars. The action's own
         # source, the methods it calls and the before filters that run for it
@@ -117,7 +128,7 @@ module RailsAiContext
         if Payload.section(cached_context, :view_templates)
           ivar_check = cross_reference_ivars(ctrl_ivars, view_ivars, rendered_templates: other_templates, api_only: api_only_app?,
                                                                      origins: origins.except(*(action_body ? resolver.assigned_ivars(action_body) : [])))
-          lines << "" << ivar_check if ivar_check
+          extras << ivar_check if ivar_check
         end
 
         # Hydrate: inject schema hints for models referenced in controller + view ivars
@@ -126,14 +137,37 @@ module RailsAiContext
           hydration = Hydrators::ViewHydrator.call(all_ivars, context: cached_context)
           hydration_text = Hydrators::HydrationFormatter.format(hydration)
           # Skip if get_controllers already injected schema hints
-          unless hydration_text.empty? || lines.any? { |l| l.include?("## Schema Hints") }
-            lines << "" << hydration_text
-          end
+          extras << hydration_text unless hydration_text.empty? || text.include?("## Schema Hints")
         end
 
-        lines.join("\n")
-      rescue => e
-        "Error assembling context: #{e.message}"
+        [ text, *extras ].reject(&:empty?).join("\n\n")
+      end
+
+      # The controller section. With rails_get_controllers off it is empty, so a controller
+      # or an action the app does not have is answered here as that tool answers it.
+      private_class_method def self.controller_text(result, name, action = nil)
+        ctx = cached_context
+        return response_text(result) if own_served?(GetControllers)
+
+        key = Payload.find_controller(ctx, name)
+        known = key || name.to_s.strip.casecmp?("ApplicationController")
+        return response_text(not_found_response("Controller", name, Payload.app_controllers(ctx).keys.sort)) unless known
+
+        (action && key && missing_action_text(ctx, key, action)).to_s
+      end
+
+      private_class_method def self.missing_action_text(ctx, name, action)
+        controllers = Payload.controllers(ctx)
+        info = controllers[name]
+        return nil unless info.is_a?(Hash)
+
+        name, info = info[:alias_of], controllers[info[:alias_of]] if controllers[info[:alias_of]].is_a?(Hash)
+        actions = Array(info[:actions]).map { |a| (a.is_a?(Hash) ? a[:name] : a).to_s }
+        return nil if actions.any? { |a| a.casecmp?(action.to_s) }
+        return nil if RailsAiContext::Introspectors::ActionSource.unlisted_action(rails_app.root, name, action.to_s,
+                                                                                 file: Payload.controller_file(ctx, name), controllers: controllers)
+
+        GetControllers.missing_action_message(name, action, actions)
       end
 
       # The templates for a controller, read from the directory Rails would
@@ -143,23 +177,23 @@ module RailsAiContext
       # convention - on a namespaced app they belong to another component
       # entirely.
       #
-      private_class_method def self.view_section_lines(snake)
+      private_class_method def self.view_section(snake)
         view_result, view_note = controller_views(snake)
-        return [] if empty?(view_result)
+        return nil if empty?(view_result)
 
-        [ "", "---", "", view_note, response_text(view_result) ].compact
+        [ view_note, response_text(view_result) ].compact.join("\n")
       end
 
       # @return [Array(MCP::Tool::Response, String, nil)] the view section and
       #   a note naming the directory it came from
       private_class_method def self.controller_views(snake)
-        namespaced = GetView.call(controller: snake, detail: "standard")
+        namespaced = compose(GetView, controller: snake, detail: "standard")
         return [ namespaced, "_Views from `app/views/#{snake}`._" ] unless empty?(namespaced)
 
         basename = snake.to_s.split("/").last
         return [ namespaced, nil ] if basename.nil? || basename == snake
 
-        flat = GetView.call(controller: basename, detail: "standard")
+        flat = compose(GetView, controller: basename, detail: "standard")
         return [ namespaced, nil ] if empty?(flat)
 
         [ flat, "_No templates under `app/views/#{snake}`; these are `app/views/#{basename}`, which Rails resolves for this controller only if it sets its own view path._" ]
@@ -264,29 +298,13 @@ module RailsAiContext
       end
 
       private_class_method def self.controller_context(controller_name)
-        lines = []
-
-        ctrl_result = GetControllers.call(controller: controller_name)
-        lines << response_text(ctrl_result)
-
+        ctrl_text = controller_text(compose(GetControllers, controller: controller_name), controller_name)
         snake = RailsAiContext::Payload.controller_route_key(cached_context, controller_name)
 
-        # Routes for this controller
-        route_result = GetRoutes.call(controller: snake)
-        unless empty?(route_result)
-          lines << "" << "---" << "" << response_text(route_result)
-        end
-
-        lines.concat(view_section_lines(snake))
-
-        lines.join("\n")
-      rescue => e
-        "Error assembling context: #{e.message}"
+        sections(ctrl_text, section_text(compose(GetRoutes, controller: snake)), view_section(snake))
       end
 
       private_class_method def self.model_context(model_name)
-        lines = []
-
         # Normalize: try as-is, then singularized, then classified
         ctx = cached_context
         models = Payload.models(ctx)
@@ -294,64 +312,49 @@ module RailsAiContext
 
         resolved_name = key || model_name
 
-        model_result = GetModelDetails.call(model: resolved_name)
-
-        # If model not found, fail fast - don't leak partial results from sub-tools
-        return response_text(model_result) if empty?(model_result)
-
-        lines << response_text(model_result)
-
-        if key && models[key][:table_name]
-          schema_result = GetSchema.call(table: models[key][:table_name])
-          unless empty?(schema_result)
-            lines << "" << "---" << "" << response_text(schema_result)
-          end
-        end
+        model_result = compose(GetModelDetails, model: resolved_name)
 
-        # Tests for this model
-        test_result = GetTestInfo.call(model: resolved_name, detail: "standard")
-        unless empty?(test_result)
-          lines << "" << "---" << "" << response_text(test_result)
-        end
+        # If model not found, fail fast - don't leak partial results from sub-tools.
+        # A model the app has still gets its schema and tests when model details is turned off.
+        served = own_served?(GetModelDetails)
+        return response_text(not_found_response("Model", model_name.to_s.strip, models.keys.sort)) if key.nil? && !served
+        return response_text(model_result) if empty?(model_result) && served
 
-        lines.join("\n")
-      rescue => e
-        "Error assembling context: #{e.message}"
+        table = key && models[key][:table_name]
+        sections(response_text(model_result), (section_text(compose(GetSchema, table: table)) if table),
+                 section_text(compose(GetTestInfo, model: resolved_name, detail: "standard")))
       end
 
-      INCLUDE_MAP = {
-        "stimulus"    => -> { GetStimulus.call(detail: "standard") },
-        "turbo"       => -> { GetTurboMap.call(detail: "standard") },
-        "services"    => -> { GetServicePattern.call(detail: "standard") },
-        "jobs"        => -> { GetJobPattern.call(detail: "standard") },
-        "conventions" => -> { GetConventions.call },
-        "helpers"     => -> { GetHelperMethods.call(detail: "standard") },
-        "env"         => -> { GetEnv.call(detail: "summary") },
-        "callbacks"   => -> { GetCallbacks.call(detail: "standard") },
-        "tests"       => -> { GetTestInfo.call(detail: "full") },
-        "config"      => -> { GetConfig.call },
-        "gems"        => -> { GetGems.call },
-        "security"    => -> { SecurityScan.call(detail: "summary") }
-      }.freeze
+      private_class_method def self.include_sections(includes)
+        includes.uniq { |key| key.to_s.downcase }.map do |key|
+          name, args = INCLUDE_MAP[key.to_s.downcase]
+          next "_`include` does not take '#{echo_input(key)}'. It takes: #{INCLUDE_MAP.keys.join(', ')}._" unless name
+
+          off = include_off_message(name, args)
+          next "_#{off}_" if off
 
-      private_class_method def self.append_includes(includes)
-        extra = +""
-        includes.each do |key|
-          handler = INCLUDE_MAP[key.to_s.downcase]
-          next unless handler
           begin
-            extra << "\n\n---\n\n" << response_text(handler.call)
+            response_text(tool_class(name).call(**args))
           rescue => e
-            extra << "\n\n---\n\n_Error loading #{key}: #{e.message}_"
+            "_Error loading #{key}: #{e.message}_"
           end
         end
-        extra
+      end
+
+      # Why the app does not serve an include's tool or config section, or nil when it does.
+      private_class_method def self.include_off_message(name, args)
+        section = GetConfig.section_named(args[:section]) if name == "rails_get_config"
+        return section.off_message if section && !section.on?
+
+        RailsAiContext::Server.skipped_tool_message(name) unless section ? section.served? : own_served?(tool_class(name))
       end
 
       private_class_method def self.feature_context(feature_name)
         # Start with full-stack feature analysis
-        analyze_result = AnalyzeFeature.call(feature: feature_name)
-        lines = [ response_text(analyze_result) ]
+        analyze_result = compose(AnalyzeFeature, feature: feature_name)
+        parts = [ response_text(analyze_result) ]
+        related = []
+        matched_models = []
 
         # Enrich with schema columns for matching models
         ctx = begin; cached_context; rescue; nil; end
@@ -361,13 +364,11 @@ module RailsAiContext
 
           models.each_key do |model_name|
             next unless model_name.downcase.include?(feature_name.downcase)
+            matched_models << model_name
             table_name = models[model_name][:table_name]
             next unless table_name
             matched_tables << table_name
-            schema_result = GetSchema.call(table: table_name)
-            unless empty?(schema_result)
-              lines << "" << "---" << "" << response_text(schema_result)
-            end
+            parts << section_text(compose(GetSchema, table: table_name))
           end
 
           # Also include schema for related models (associated tables) if the
@@ -382,21 +383,26 @@ module RailsAiContext
                 c_name.downcase.include?(feature_name.pluralize.downcase)
             end
             if related_ctrls.any?
-              lines << "" << "## Related Controllers (by name)"
+              related << "## Related Controllers (by name)"
               related_ctrls.each do |c_name, c|
                 actions = (c[:actions] || []).map { |a| a.is_a?(Hash) ? a[:name] : a }.compact
-                lines << "- **#{c_name}** - #{actions.join(', ')}"
+                related << "- **#{c_name}** - #{actions.join(', ')}"
               end
             end
-
           end
         end
 
-        lines.join("\n")
+        text = [ sections(*parts), related.join("\n") ].reject(&:empty?).join("\n\n")
+        return text unless text.empty? && !own_served?(AnalyzeFeature)
+
+        # With rails_analyze_feature off, only model and controller names were matched.
+        return "The model names that hold '#{echo_input(feature_name)}': #{matched_models.sort.join(', ')}." if matched_models.any?
+
+        "No matches found for '#{echo_input(feature_name)}'. No model or controller name holds this keyword.#{AnalyzeFeature.model_names_hint(ctx)}"
       rescue => e
         # Fall back to plain analyze_feature on error
         RailsAiContext.debug_fail(e, label: "feature_context")
-        response_text(AnalyzeFeature.call(feature: feature_name))
+        response_text(compose(AnalyzeFeature, feature: feature_name))
       end
     end
   end

data/lib/rails_ai_context/tools/get_controllers.rb

@@ -287,6 +287,10 @@ module RailsAiContext
         end
       end
 
+      def self.missing_action_message(controller_name, action_name, actions)
+        "Action '#{echo_input(action_name)}' not found in #{controller_name}. Available: #{actions.join(', ')}"
+      end
+
       private_class_method def self.format_action_source(controller_name, info, action_name)
         # An alias is the same class: its actions are read from the controller it names.
         target = info[:alias_of] && RailsAiContext::Payload.controllers(cached_context)[info[:alias_of]]
@@ -304,7 +308,7 @@ module RailsAiContext
           unlisted = RailsAiContext::Introspectors::ActionSource.unlisted_action(rails_app.root, controller_name, action_name,
             file: carried, controllers: RailsAiContext::Payload.controllers(cached_context))
           unless unlisted
-            return empty_response("Action '#{echo_input(action_name)}' not found in #{controller_name}. Available: #{actions.join(', ')}")
+            return empty_response(missing_action_message(controller_name, action_name, actions))
           end
 
           action_name = unlisted[:name]
@@ -681,12 +685,11 @@ module RailsAiContext
         model_name = RailsAiContext::Introspectors::TableName.model_for(
           ctrl_path.split("/").last.singularize.camelize, nil, RailsAiContext::Payload.models(ctx)
         )
-        lines << ""
-        lines << "_Next: `rails_get_routes(controller:\"#{ctrl_path}\")` for routes"
-        lines << " | `rails_get_model_details(model:\"#{model_name}\")` for model" if model_name
         # The full path, which is the directory Rails resolves templates in:
         # the basename reads another component's views on a namespaced app.
-        lines << " | `rails_get_view(controller:\"#{ctrl_path}\")` for views_"
+        add_next_hint(lines, pointer("rails_get_routes", %(controller:"#{ctrl_path}"), "for routes"),
+                      (pointer("rails_get_model_details", %(model:"#{model_name}"), "for model") if model_name),
+                      pointer("rails_get_view", %(controller:"#{ctrl_path}"), "for views"), lines: true)
 
         lines.join("\n")
       end

data/lib/rails_ai_context/tools/get_conventions.rb

@@ -4,18 +4,13 @@ module RailsAiContext
   module Tools
     class GetConventions < BaseTool
       tool_name "rails_get_conventions"
+      section_renderer!
       description "Detect app architecture and conventions: API-only vs Hotwire, design patterns, directory layout. " \
         "Use when: starting work on an unfamiliar codebase, choosing implementation patterns, or checking what frameworks are in use. " \
         "No parameters needed. Returns architecture style, detected patterns (STI, service objects), and notable config files."
 
       input_schema(properties: {})
 
-      guide_row(
-        order: 23,
-        mcp: "rails_get_conventions",
-        summary: "App patterns: auth checks, flash messages, test patterns"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       def self.call(server_context: nil)

data/lib/rails_ai_context/tools/get_engines.rb

@@ -4,17 +4,12 @@ module RailsAiContext
   module Tools
     class GetEngines < BaseTool
       tool_name "rails_get_engines"
+      section_renderer!
       description "Get what config/routes.rb mounts - engines and plain Rack apps alike, with known-engine descriptions - the app's own in-repo engines, plugins and modules, and every loaded Rails::Engine subclass (routes and model counts). " \
         "Use when: checking what is mounted where, finding an admin dashboard's path, listing the repository's own engines, or understanding engine-provided routes."
 
       input_schema(properties: {})
 
-      guide_row(
-        order: 42,
-        mcp: "rails_get_engines",
-        summary: "Mounted apps (engines and Rack apps) + in-repo engines + loaded engine classes with route/model counts"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       def self.call(server_context: nil)

data/lib/rails_ai_context/tools/get_env.rb

@@ -7,6 +7,7 @@ module RailsAiContext
   module Tools
     class GetEnv < BaseTool
       tool_name "rails_get_env"
+      section_renderer!
       description "Discover environment variables, external service dependencies, and credentials keys used by the app. " \
         "Use when: setting up a development environment, debugging missing config, or auditing external dependencies. " \
         "Scans .rb, .rake, ERB views and config YAML for ENV[], plus .env.example, Dockerfile, the env Kamal's config/deploy.yml sets, config gem settings and Anyway::Config keys, external HTTP calls, and credentials keys (never values)."
@@ -17,12 +18,6 @@ module RailsAiContext
         }
       )
 
-      guide_row(
-        order: 17,
-        mcp: "rails_get_env",
-        summary: "Environment variables + credentials keys (not values)"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       # One wording for the same fact on both detail levels.

data/lib/rails_ai_context/tools/get_env_config.rb

@@ -4,11 +4,12 @@ module RailsAiContext
   module Tools
     class GetEnvConfig < BaseTool
       tool_name "rails_get_env_config"
+      section_renderer!
       description "Get per-environment configuration from config/environments/*.rb: notable toggles (force_ssl, eager_load, caching, log level, queue adapter, mailer delivery) and every config key each environment sets, " \
         "plus the keys config/application.rb sets for every environment (config.x included) and the keys each config_for YAML file gives. " \
         "Use when: comparing development vs production behavior, debugging env-specific bugs, or checking what a custom environment changes. " \
         "Filter with environment:\"production\". Omit for all environments. " \
-        "For environment variables and ENV[] usage, use rails_get_env instead."
+        "For environment variables and ENV[] usage, use rails_get_config(section:\"env\") instead."
 
       input_schema(
         properties: {
@@ -27,13 +28,6 @@ module RailsAiContext
         }
       )
 
-      guide_row(
-        order: 45,
-        mcp: "rails_get_env_config(environment:\"production\")",
-        cli_args: "environment=production",
-        summary: "Per-environment config: notable toggles + config keys each env sets"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       def self.call(environment: nil, offset: 0, limit: nil, server_context: nil)

data/lib/rails_ai_context/tools/get_frontend_stack.rb

@@ -4,6 +4,7 @@ module RailsAiContext
   module Tools
     class GetFrontendStack < BaseTool
       tool_name "rails_get_frontend_stack"
+      section_renderer!
       description "Returns the app's frontend stack: framework, build tool, state management, TypeScript config, " \
         "component directories, and package manager. " \
         "Use when: scaffolding new frontend features, choosing libraries, or understanding the JS/TS build pipeline. " \
@@ -15,12 +16,6 @@ module RailsAiContext
         }
       )
 
-      guide_row(
-        order: 29,
-        mcp: "rails_get_frontend_stack",
-        summary: "React/Vue/Svelte/Angular, Inertia, TypeScript, package manager"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       def self.call(detail: "standard", server_context: nil)

data/lib/rails_ai_context/tools/get_gems.rb

@@ -4,6 +4,7 @@ module RailsAiContext
   module Tools
     class GetGems < BaseTool
       tool_name "rails_get_gems"
+      section_renderer!
       description "Get notable gems from Gemfile.lock grouped by category (auth, jobs, frontend, API, database, testing, deploy and more). " \
         "Use when: checking what libraries are available before adding a dependency, or understanding the tech stack. " \
         "Filter with category:\"auth\" or category:\"database\". Omit for all categories."
@@ -26,12 +27,6 @@ module RailsAiContext
         }
       )
 
-      guide_row(
-        order: 22,
-        mcp: "rails_get_gems",
-        summary: "Notable gems with versions, categories, config file locations"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       # A `config/initializers/` hint is resolved through PathResolver, so the

data/lib/rails_ai_context/tools/get_helper_methods.rb

@@ -55,7 +55,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 20,
+        order: 19,
         mcp: "rails_get_helper_methods",
         summary: "App + framework helpers with view cross-references"
       )
@@ -208,11 +208,10 @@ module RailsAiContext
         # named for, and only those the app has: ApplicationHelper has no
         # controller of its own to send the reader to.
         route_key = relative_under(file_path, helper_dirs).delete_suffix(".rb").delete_suffix("_helper")
-        hints = []
-        hints << "`rails_get_view(controller:\"#{route_key}\")` for views" if RailsAiContext::PathResolver.view_dirs(root).any? { |dir| Dir.exist?(File.join(dir, route_key)) }
+        views = RailsAiContext::PathResolver.view_dirs(root).any? { |dir| Dir.exist?(File.join(dir, route_key)) }
         controller = Payload.controller_for_route_key(cached_context, route_key)&.first
-        hints << "`rails_get_controllers(controller:\"#{controller}\")` for controller" if controller
-        lines << "" << "_Next: #{hints.join(' | ')}_" if hints.any?
+        add_next_hint(lines, (pointer("rails_get_view", %(controller:"#{route_key}"), "for views") if views),
+                      (pointer("rails_get_controllers", %(controller:"#{controller}"), "for controller") if controller))
 
         text_response(lines.join("\n"))
       end

data/lib/rails_ai_context/tools/get_i18n.rb

@@ -4,6 +4,7 @@ module RailsAiContext
   module Tools
     class GetI18n < BaseTool
       tool_name "rails_get_i18n"
+      section_renderer!
       description "Get I18n setup: default/available locales, backend, locale files with key counts, per-locale coverage vs the default locale, and fallbacks. " \
         "Use when: adding translations, checking locale coverage before shipping, or finding which file defines a locale. " \
         "Filter with locale:\"fr\". Omit for the full picture."
@@ -25,13 +26,6 @@ module RailsAiContext
         }
       )
 
-      guide_row(
-        order: 40,
-        mcp: "rails_get_i18n(locale:\"fr\")",
-        cli_args: "locale=fr",
-        summary: "Locales, locale files with key counts, per-locale coverage, fallbacks"
-      )
-
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
       def self.call(locale: nil, offset: 0, limit: nil, server_context: nil)

data/lib/rails_ai_context/tools/get_job_pattern.rb

@@ -383,7 +383,7 @@ module RailsAiContext
         end
 
         # Cross-reference hints
-        lines << "" << "_Next: `rails_search_code(pattern:\"#{class_name}\")` for all references_"
+        add_next_hint(lines, pointer("rails_search_code", %(pattern:"#{class_name}"), "for all references"))
 
         text_response(lines.join("\n"))
       end

data/lib/rails_ai_context/tools/get_mailers.rb

@@ -28,7 +28,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 41,
+        order: 35,
         mcp: "rails_get_mailers(mailer:\"X\")",
         cli_args: "mailer=X",
         summary: "Mailer classes with delivery actions and delivery method, mailboxes and their routing"

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -217,8 +217,8 @@ module RailsAiContext
               end
               differ = others.reject { |_, other| other[:columns] == table_data[:columns] }.map(&:first)
               if differ.any?
-                lines << "" << "Columns of `#{data[:table_name]}` in #{source}; the table differs in #{differ.join(", ")}: " \
-                               "`rails_get_schema(table:\"#{data[:table_name]}\")` lists each."
+                schema = pointer("rails_get_schema", %(table:"#{data[:table_name]}"), "lists each.")
+                lines << "" << "Columns of `#{data[:table_name]}` in #{source}; the table differs in #{differ.join(", ")}#{schema ? ": #{schema}" : "."}"
               end
             end
             lines << ignored_columns_line(ignored) if ignored.any?
@@ -575,15 +575,12 @@ module RailsAiContext
           end
         end
 
-        # Cross-reference hints - guide AI to related tools
-        hints = []
-        hints << "`rails_get_schema(table:\"#{data[:table_name]}\")` for columns/indexes" if data[:table_name]
         # Only a controller the app has: the conventional name is a guess, and
         # a hint naming a class that does not exist sends the reader nowhere.
         controller_name = Payload.controller_for_route_key(cached_context, name.underscore.pluralize)&.first
-        hints << "`rails_get_controllers(controller:\"#{controller_name}\")` for actions" if controller_name
-        hints << "`rails_analyze_feature(feature:\"#{name}\")` for full-stack view"
-        lines << "" << "_Next: #{hints.join(' | ')}_"
+        add_next_hint(lines, (pointer("rails_get_schema", %(table:"#{data[:table_name]}"), "for columns/indexes") if data[:table_name]),
+                      (pointer("rails_get_controllers", %(controller:"#{controller_name}"), "for actions") if controller_name),
+                      pointer("rails_analyze_feature", %(feature:"#{name}"), "for full-stack view"))
 
         lines.join("\n")
       end

data/lib/rails_ai_context/tools/get_partial_interface.rb

@@ -22,7 +22,7 @@ module RailsAiContext
       )
 
       guide_row(
-        order: 18,
+        order: 17,
         mcp: "rails_get_partial_interface(partial:\"X\")",
         cli_args: "partial=X",
         summary: "Partial locals contract: what to pass + usage examples"
@@ -79,7 +79,7 @@ module RailsAiContext
         unless located
           available = view_dirs.flat_map { |dir| find_available_partials(dir, root) }.uniq.sort.first(30)
           return not_found_response("Partial", partial, available,
-            recovery_tool: "Call rails_get_view(detail:\"summary\") to see all views and partials", note: static_engine_views_note)
+            recovery_tool: call_pointer("rails_get_view", %(detail:"summary"), "to see all views and partials"), note: static_engine_views_note)
         end
 
         file_path = located.realpath
@@ -202,8 +202,7 @@ module RailsAiContext
           lines << RailsAiContext::Redaction.redact_source(source, path: relative_path)
           lines << "```"
         else
-          lines << ""
-          lines << "_Next: `rails_get_view(path:\"#{partial_name}\")` for full file content_"
+          add_next_hint(lines, pointer("rails_get_view", %(path:"#{partial_name}"), "for full file content"))
         end
 
         text_response(lines.join("\n"))