ruby_llm-code_mode 0.4.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2a3805466e08fb043ab80695cd7dd7d234bc6cb1266ed2c0e2af790d3154ca7
-  data.tar.gz: 54784bff8beecd426ce7d9ec9cdbd632463a88c51060891c966d475a65fa1798
+  metadata.gz: 2971c55a0ddb64f36fac74369b9f591a457d7f790fef69629c840105ee44a41f
+  data.tar.gz: ce4cb05af563703b265ac6cf39e4dcfd726cfc4fcd34d3c346e2e2a9783d6613
 SHA512:
-  metadata.gz: ce78787e62249f947b126dd31f13f30ae76160b85de5373e0679ea259e7f31f162df811f55372a67ba7ec2bee97f44ec7d9af372a7df67d098eb7361a41de3e6
-  data.tar.gz: 93d477c68ed0ae001f068c18e729791c1eb302687a82eafc97bc6013306eb9d5998896d11d9c172fe3fc77e55dfad9018b36968809a0559ef256804055c16ee8
+  metadata.gz: e5cc54963c906914bcc93c8ce4bc07ca92aa069993746d1b471bbd7572687b9aea89b6b241cb09cbc0323ecb42318b0cc6f921c89b4ab2fe81f7b65d60868201
+  data.tar.gz: 036fdc62c104e9c3afe3309459cc1da6d5a8693ce28078f358d6af8f51e33f59d67b6a8f29f2e0504354692bee1c944d0917599423e14edf7317fd3e8b33eb15

data/README.md

@@ -229,6 +229,47 @@ tool.execute(code: 'SB.call("user_search", q: "...")')
   `add_tools`/`add_mcps` raise — create a new instance instead. Instances
   without additions share the class configuration.
 
+### Tool catalog
+
+An MCP server can bind dozens of tools, and listing every one — with its full
+description and parameters — in the tool description can drown the system
+prompt. The `tool_catalog` DSL swaps the full listing for a compact index and
+lets the model find tools on demand from inside the sandbox:
+
+```ruby
+class DocsResearch < RubyLLM::CodeMode
+  mcps docs
+  tool_catalog                                   # defaults: search_limit: 10, preview_chars: 20
+  # tool_catalog search_limit: 5, preview_chars: 40
+end
+```
+
+With the catalog enabled the description lists each tool as a single line —
+name plus the first `preview_chars` characters of its description — plus the
+instructions for two internal RPCs the sandboxed code calls like any host
+tool:
+
+```ruby
+matches = SB.call("search_tools", query: "azure blob upload")
+# => { query: ..., count: ..., tools: [{ name:, description: }, ...] }
+usage = SB.call("tool_details", name: "azure_storage_blob_upload")
+# => { name:, description:, parameters: [{ name:, type:, required:, description: }] }
+```
+
+- The search matches every term of the query (case-insensitive) against the
+  tool **name and description**, ranks name matches first and returns at most
+  `search_limit` results.
+- `tool_details` raises a rescuable `SB::ToolError` for unknown names,
+  suggesting a few similar tools when there are any.
+- Without `tool_catalog` nothing changes: every tool stays listed in full.
+- `search_tools` and `tool_details` are reserved names — binding a tool with
+  either raises at definition time. The two catalog RPCs also count against
+  the 64-slot RPC budget, so at most 62 tools can be bound with the catalog
+  on (enforced at definition time).
+- Subclasses inherit the catalog settings, and per-instance additions
+  (`add_tools`/`add_mcps`) are searchable on that instance too. Read the
+  current settings with `MyTool.catalog_settings` (nil when off).
+
 ### Sandbox limits
 
 Defaults: `timeout_ms: 30_000` (wall clock), `fuel_ms: 10_000` (CPU budget).

data/lib/ruby_llm/code_mode/catalog.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class CodeMode
+    # On-demand tool catalog (opt-in via the .tool_catalog DSL): instead of
+    # listing every bound tool in full in the description, the model gets a
+    # compact index (name plus a truncated description) and two internal RPC
+    # handlers — `search_tools` (find tools by name/description) and
+    # `tool_details` (full usage of one tool). The handlers are built per
+    # tools hash: the class configuration searches the class tools, and an
+    # instance configuration rebinds them over the class tools plus its own
+    # additions (see #add_tools).
+    module Catalog
+      DEFAULT_SEARCH_LIMIT = 10
+      DEFAULT_PREVIEW_CHARS = 20
+
+      SEARCH_NAME = "search_tools"
+      DETAILS_NAME = "tool_details"
+
+      # Names no regular tool may bind, catalog enabled or not: the guest
+      # calls them unqualified, so a colliding bound tool would become
+      # unreachable as soon as the catalog is turned on.
+      RESERVED_NAMES = [SEARCH_NAME, DETAILS_NAME].freeze
+
+      class << self
+        # The two guest-facing handlers over `tools` (a name => ToolEntry
+        # hash) with `catalog` settings. Handler failures raise, which the
+        # guest sees as rescuable SB::ToolError (class + message only).
+        def rpc_handlers(tools, catalog)
+          {
+            SEARCH_NAME => ->(args) { search_call(tools, catalog, args) },
+            DETAILS_NAME => ->(args) { details_call(tools, args) }
+          }
+        end
+
+        # The compact "## Host tools" description section: the search/details
+        # instructions plus one line per tool — its name and at most
+        # `preview_chars` characters of its description.
+        def section(tools, catalog)
+          return nil if tools.empty?
+
+          intro = <<~INTRO
+            Search before calling: `SB.call('#{SEARCH_NAME}', query: 'terms')` finds tools
+            by name or description (at most #{catalog.search_limit} matches), and
+            `SB.call('#{DETAILS_NAME}', name: 'name')` returns one tool's full usage —
+            call it before using a tool for the first time.
+          INTRO
+
+          [
+            "## Host tools (#{tools.size} available)",
+            intro.rstrip,
+            *tools.values.map { |entry| preview_line(entry, catalog.preview_chars) }
+          ].join("\n")
+        end
+
+        # Tools whose name or description contains every term of `query`
+        # (case-insensitive; terms are sequences of word characters). Tools
+        # matched by name rank before description-only matches, each group
+        # alphabetical. At most `limit` results: `{ name:, description: }`.
+        def search(tools, query, limit)
+          terms = terms_of(query)
+          return [] if terms.empty?
+
+          tools.values.filter_map { |entry| match(entry, terms) }
+                .sort_by { |score, name, _| [score, name] }
+                .first(limit)
+                .map { |_, _, entry| { name: entry.name, description: entry.tool.description.to_s } }
+        end
+
+        # Full usage of one tool — name, description and the declared
+        # parameters — or nil when the name is not bound.
+        def details(tools, name)
+          entry = tools[name.to_s]
+          return nil unless entry
+
+          {
+            name: entry.name,
+            description: entry.tool.description.to_s,
+            parameters: Registry.parameter_specs(entry.tool)
+          }
+        end
+
+        # A few bound names similar to `name` (sharing any of its terms),
+        # used in the unknown-tool error message.
+        def suggestions(tools, name)
+          terms = terms_of(name)
+          return [] if terms.empty?
+
+          tools.values.filter_map do |entry|
+            haystack = "#{entry.name} #{entry.tool.description}".downcase
+            entry.name if terms.any? { |term| haystack.include?(term) }
+          end.first(3)
+        end
+
+        private
+
+        def search_call(tools, catalog, args)
+          query = string_arg(args, SEARCH_NAME, "query")
+          results = search(tools, query, catalog.search_limit)
+          { query: query, count: results.size, tools: results }
+        end
+
+        def details_call(tools, args)
+          name = string_arg(args, DETAILS_NAME, "name")
+          found = details(tools, name)
+          return found if found
+
+          hints = suggestions(tools, name)
+          hint = hints.empty? ? "" : " — similar tools: #{hints.join(', ')}"
+          raise ArgumentError, "unknown tool #{name.inspect}#{hint}"
+        end
+
+        # Both catalog RPCs take exactly one non-empty string argument,
+        # passed by the guest as a JSON object (string keys).
+        def string_arg(args, rpc, key)
+          unless args.is_a?(Hash)
+            raise ArgumentError, "#{rpc} expects a hash of arguments, got #{args.class}"
+          end
+
+          value = args[key]
+          return value if value.is_a?(String) && !value.strip.empty?
+
+          raise ArgumentError, "#{rpc} requires a non-empty '#{key}' string"
+        end
+
+        def terms_of(text)
+          text.to_s.split(/[\W_]+/).reject(&:empty?).map(&:downcase).uniq
+        end
+
+        # A [score, name, entry] triple for a tool matching every term —
+        # score 0 when at least one term hits the name, 1 otherwise — or
+        # nil when the tool does not match.
+        def match(entry, terms)
+          name = entry.name.to_s.downcase
+          description = entry.tool.description.to_s.downcase
+          return unless terms.all? { |term| name.include?(term) || description.include?(term) }
+
+          [terms.any? { |term| name.include?(term) } ? 0 : 1, entry.name, entry]
+        end
+
+        def preview_line(entry, preview_chars)
+          line = "- `#{entry.name}`"
+          preview = entry.tool.description.to_s.lines.first.to_s.strip
+          preview = "#{preview[0, preview_chars]}…" if preview.length > preview_chars
+          line += " — #{preview}" unless preview.empty?
+          line
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/code_mode/description.rb

@@ -34,18 +34,22 @@ module RubyLLM
     class << self
       # Builds the description the model sees for this tool: the fixed
       # "How to use" text, one section per mount kind listing each mounted
-      # folder, the "Host tools (call with SB.call)" section with every
-      # bound tool and its parameters, and the "Server notes" section with
-      # each MCP server's instructions. `extra_tools`/`extra_mcps` carry
-      # the per-instance additions (see #add_tools/#add_mcps); with no
-      # extras the output is identical to the class-level description.
+      # folder, the "Host tools" section — the full listing with every
+      # bound tool and its parameters, or the compact catalog index with
+      # the search/details instructions when the tool catalog is on — and
+      # the "Server notes" section with each MCP server's instructions.
+      # `extra_tools`/`extra_mcps` carry the per-instance additions (see
+      # #add_tools/#add_mcps); with no extras the output is identical to
+      # the class-level description.
       def build_description(extra_tools: {}, extra_mcps: [])
         read_only, read_write = mounts.partition { |m| m.mode == :read_only }
+        all_tools = tools.merge(extra_tools)
+        catalog = catalog_settings
         [
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
           folder_section("## Read-write folders (readable and writable)", read_write),
-          Registry.tools_section(tools.merge(extra_tools)),
+          catalog ? Catalog.section(all_tools, catalog) : Registry.tools_section(all_tools),
           Registry.server_notes_section(mcps + extra_mcps)
         ].compact.join("\n\n")
       end

data/lib/ruby_llm/code_mode/dsl.rb

@@ -49,7 +49,7 @@ module RubyLLM
       def tools(*args, **kwargs)
         return @tools ||= {} if args.empty? && kwargs.empty?
 
-        Registry.register_tools(tools, args, kwargs)
+        Registry.register_tools(tools, args, kwargs, reservation: catalog_reservation)
       end
 
       # Connects MCP server(s) and binds all their tools into the sandbox:
@@ -75,7 +75,48 @@ module RubyLLM
       def mcps(*servers, **inputs)
         return @mcps ||= [] if servers.empty? && inputs.empty?
 
-        Registry.register_mcps(tools, mcps, servers, inputs)
+        Registry.register_mcps(tools, mcps, servers, inputs, reservation: catalog_reservation)
+      end
+
+      # Opts the class into the on-demand tool catalog: the description
+      # stops listing every bound tool in full and shows a compact index
+      # (name plus a short description preview) instead, and the guest gets
+      # two internal RPCs to find and inspect tools:
+      #
+      #   class Research < RubyLLM::CodeMode
+      #     mcps DocsServer
+      #     tool_catalog                                  # defaults
+      #     tool_catalog search_limit: 5, preview_chars: 40
+      #   end
+      #
+      # A bare call enables the catalog with the defaults; passing any
+      # option (re)sets it: `search_limit:` (matches per search, default
+      # 10) and `preview_chars:` (description preview length in the
+      # listing, default 20). Called on an already-enabled class without
+      # options it returns the current settings. Use .catalog_settings to
+      # read the state without side effects (nil when the catalog is off).
+      # The two catalog RPCs count against the 64-slot RPC budget, so with
+      # the catalog on at most 62 tools can be bound (enforced at
+      # definition time, like the other limits).
+      def tool_catalog(search_limit: nil, preview_chars: nil)
+        if search_limit.nil? && preview_chars.nil?
+          return catalog_settings if catalog_settings
+          # A bare first call falls through and enables with the defaults.
+        end
+
+        catalog = ToolCatalog.new(
+          search_limit: search_limit || Catalog::DEFAULT_SEARCH_LIMIT,
+          preview_chars: preview_chars || Catalog::DEFAULT_PREVIEW_CHARS
+        )
+        validate_tool_catalog!(catalog)
+        @tool_catalog = catalog.freeze
+      end
+
+      # The tool-catalog settings, or nil when the catalog is off. Unlike
+      # .tool_catalog, reading never enables anything: this is what
+      # description builds, configurations and instances consult.
+      def catalog_settings
+        instance_variable_defined?(:@tool_catalog) ? @tool_catalog : nil
       end
 
       # The mounts declared so far, as Mount structs (read-only and
@@ -88,15 +129,16 @@ module RubyLLM
 
       # Builds and memoizes the SecurityBox::Configuration for this class:
       # the default limits (timeout_ms: 30_000, fuel_ms: 10_000), the
-      # declared mounts and one RPC handler per bound tool. Memoized per
-      # class; subclasses build their own. Tool instances without
-      # per-instance additions share it (see #add_tools).
+      # declared mounts and one RPC handler per bound tool (plus the two
+      # catalog handlers when the tool catalog is on). Memoized per class;
+      # subclasses build their own. Tool instances without per-instance
+      # additions share it (see #add_tools).
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
           fuel_ms: DEFAULT_FUEL_MS,
           mounts: mounts.map(&:payload),
-          rpcs: Registry.rpc_handlers(tools)
+          rpcs: rpc_handlers
         )
       end
 
@@ -109,18 +151,51 @@ module RubyLLM
       end
 
       # Ruby hook: subclasses start with a copy of the parent's mounts,
-      # tools and MCP servers (entries and instances shared), and their own
-      # configuration memo so limits/rpcs are rebuilt per class.
+      # tools, MCP servers and tool-catalog settings (entries and instances
+      # shared), and their own configuration memo so limits/rpcs are
+      # rebuilt per class.
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@mounts, mounts.dup)
         subclass.instance_variable_set(:@tools, tools.dup)
         subclass.instance_variable_set(:@mcps, mcps.dup)
+        subclass.instance_variable_set(:@tool_catalog, catalog_settings)
         subclass.instance_variable_set(:@configuration, nil)
       end
 
       private
 
+      # One RPC handler per bound tool, plus the two catalog handlers when
+      # the tool catalog is on (they search the class tools only; instances
+      # with additions rebind them over the merged set).
+      def rpc_handlers
+        handlers = Registry.rpc_handlers(tools)
+        return handlers unless catalog_settings
+
+        handlers.merge(Catalog.rpc_handlers(tools, catalog_settings))
+      end
+
+      # RPC slots the tool catalog takes beyond the tools themselves.
+      def catalog_reservation
+        catalog_settings ? Catalog::RESERVED_NAMES.size : 0
+      end
+
+      def validate_tool_catalog!(catalog)
+        %i[search_limit preview_chars].each do |option|
+          value = catalog.send(option)
+          unless value.is_a?(Integer) && value.positive?
+            raise ArgumentError,
+                  "tool_catalog #{option} must be a positive Integer, got #{value.inspect}"
+          end
+        end
+        slots = tools.size + Catalog::RESERVED_NAMES.size
+        return if slots <= MAX_TOOLS
+
+        raise ArgumentError,
+              "tool_catalog needs #{Catalog::RESERVED_NAMES.size} extra RPC slots but " \
+              "#{tools.size} tools are already bound (the limit is #{MAX_TOOLS})"
+      end
+
       def add_mount(source, dest, mode, description)
         mounts << Mount.new(
           host: File.expand_path(source.to_s),

data/lib/ruby_llm/code_mode/instance_methods.rb

@@ -15,7 +15,8 @@ module RubyLLM
     def add_tools(*args, **kwargs)
       ensure_extendable!
 
-      Registry.register_tools(instance_tools, args, kwargs, reserved: self.class.tools)
+      Registry.register_tools(instance_tools, args, kwargs,
+                              reserved: self.class.tools, reservation: catalog_reservation)
     end
 
     # Connects MCP server(s) onto this specific instance, on top of the
@@ -25,7 +26,8 @@ module RubyLLM
     def add_mcps(*servers, **inputs)
       ensure_extendable!
 
-      Registry.register_mcps(instance_tools, instance_mcps, servers, inputs, reserved: self.class.tools)
+      Registry.register_mcps(instance_tools, instance_mcps, servers, inputs,
+                             reserved: self.class.tools, reservation: catalog_reservation)
     end
 
     # The description this instance presents to the model: the class-level
@@ -67,9 +69,17 @@ module RubyLLM
       @instance_mcps ||= []
     end
 
+    # RPC slots the class-level tool catalog takes beyond the tools.
+    def catalog_reservation
+      self.class.catalog_settings ? Catalog::RESERVED_NAMES.size : 0
+    end
+
     # Instances without additions share the class configuration; instances
     # with additions build their own, merging the class rpcs with the
-    # instance ones (names cannot collide — the registrations validate that).
+    # instance ones (names cannot collide — the registrations validate
+    # that). With the tool catalog on, the two catalog handlers are rebound
+    # over the merged tools so the guest can search the instance additions
+    # too.
     def configuration
       return self.class.configuration if instance_tools.empty? && instance_mcps.empty?
 
@@ -77,10 +87,18 @@ module RubyLLM
         timeout_ms: DEFAULT_TIMEOUT_MS,
         fuel_ms: DEFAULT_FUEL_MS,
         mounts: self.class.mounts.map(&:payload),
-        rpcs: self.class.configuration.rpcs.merge(Registry.rpc_handlers(instance_tools))
+        rpcs: instance_rpcs
       )
     end
 
+    def instance_rpcs
+      rpcs = self.class.configuration.rpcs.merge(Registry.rpc_handlers(instance_tools))
+      return rpcs unless self.class.catalog_settings
+
+      merged = self.class.tools.merge(instance_tools)
+      rpcs.merge(Catalog.rpc_handlers(merged, self.class.catalog_settings))
+    end
+
     def sandbox
       @sandbox ||= SecurityBox::Sandbox.new(configuration)
     end

data/lib/ruby_llm/code_mode/registry.rb

@@ -15,18 +15,20 @@ module RubyLLM
         # arguments or kwargs). All-or-nothing: on any failure `target` is
         # restored and the error re-raised. `reserved` lists names already
         # taken elsewhere (e.g. the class-level bindings for instance
-        # additions); duplicates against it raise.
-        def register_tools(target, args, kwargs, reserved: EMPTY)
+        # additions); duplicates against it raise. `reservation` counts RPC
+        # slots taken by extras beyond the tools themselves (the tool
+        # catalog's two handlers) against the MAX_TOOLS budget.
+        def register_tools(target, args, kwargs, reserved: EMPTY, reservation: 0)
           snapshot = target.dup
           begin
             args.flatten(1).each do |item|
               if item.is_a?(Hash)
-                item.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+                item.each { |name, bound| add_tool(target, bound, name.to_s, reserved, reservation) }
               else
-                add_tool(target, item, nil, reserved)
+                add_tool(target, item, nil, reserved, reservation)
               end
             end
-            kwargs.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+            kwargs.each { |name, bound| add_tool(target, bound, name.to_s, reserved, reservation) }
           rescue StandardError
             target.replace(snapshot)
             raise
@@ -37,7 +39,7 @@ module RubyLLM
         # Connects MCP server(s) and binds all their tools into
         # `target_tools`/`target_mcps`. All-or-nothing across both
         # collections.
-        def register_mcps(target_tools, target_mcps, servers, inputs, reserved: EMPTY)
+        def register_mcps(target_tools, target_mcps, servers, inputs, reserved: EMPTY, reservation: 0)
           snapshot_tools = target_tools.dup
           snapshot_mcps = target_mcps.dup
           flat = servers.flatten(1)
@@ -47,7 +49,7 @@ module RubyLLM
           end
 
           normalize_mcp_servers(flat, inputs).each do |server|
-            bind_mcp_server(target_tools, target_mcps, server, reserved)
+            bind_mcp_server(target_tools, target_mcps, server, reserved, reservation)
           end
           target_mcps
         rescue StandardError
@@ -56,7 +58,7 @@ module RubyLLM
           raise
         end
 
-        # One RPC handler per bound tool, ready for
+        # The RPC handler per bound tool, ready for
         # SecurityBox::Configuration.build(rpcs:). Each handler validates
         # that the guest passed a hash of arguments, forwards the call to
         # the tool instance (string keys symbolized, schema mistakes coming
@@ -66,6 +68,26 @@ module RubyLLM
           tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
         end
 
+        # One hash per declared parameter — name, type, required flag and
+        # description — from the tool's JSON schema. Shared by the rendered
+        # description lines (param_lines) and the tool catalog's
+        # tool_details handler.
+        def parameter_specs(tool)
+          schema = tool.parameters_schema || {}
+          properties = schema["properties"] || {}
+          required = schema["required"] || []
+
+          properties.filter_map do |param, spec|
+            spec ||= {}
+            {
+              name: param.to_s,
+              type: spec["type"] || "string",
+              required: required.include?(param),
+              description: spec["description"].to_s
+            }
+          end
+        end
+
         # The "## Host tools (call with SB.call)" description section: the
         # shared intro plus one line per tool with its description and
         # parameter docs. Returns nil when no tools are bound, so the
@@ -97,7 +119,7 @@ module RubyLLM
 
         private
 
-        def add_tool(target, bound, name, reserved)
+        def add_tool(target, bound, name, reserved, reservation = 0)
           instance = normalize_bound_tool(bound)
           if instance.is_a?(RubyLLM::CodeMode)
             raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
@@ -108,9 +130,15 @@ module RubyLLM
           if target.key?(name) || reserved.key?(name)
             raise ArgumentError, "tool name #{name.inspect} is already bound"
           end
-          total = target.size + reserved.size
+          if Catalog::RESERVED_NAMES.include?(name)
+            raise ArgumentError,
+                  "tool name #{name.inspect} is reserved for the tool catalog (see .tool_catalog)"
+          end
+          total = target.size + reserved.size + reservation
           if total >= MAX_TOOLS
-            raise ArgumentError, "too many tools (#{total + 1}); the limit is #{MAX_TOOLS}"
+            raise ArgumentError,
+                  "too many tools (#{total + 1}); the limit is #{MAX_TOOLS - reservation}" \
+                  "#{reservation.positive? ? ' with the tool catalog enabled' : ''}"
           end
 
           target[name] = ToolEntry.new(name: name, tool: instance)
@@ -187,22 +215,22 @@ module RubyLLM
           end
         end
 
-        def bind_mcp_server(target_tools, target_mcps, server, reserved)
+        def bind_mcp_server(target_tools, target_mcps, server, reserved, reservation)
           # Fetching .tools connects to the server; snapshot the instructions
           # right after, so description builds never touch the network.
           tools_list = server.tools
           target_mcps << McpEntry.new(
             name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
           )
-          tools_list.each { |tool| bind_mcp_tool(target_tools, server, tool, reserved) }
+          tools_list.each { |tool| bind_mcp_tool(target_tools, server, tool, reserved, reservation) }
         end
 
-        def bind_mcp_tool(target_tools, server, tool, reserved)
+        def bind_mcp_tool(target_tools, server, tool, reserved, reservation)
           name = tool_binding_name(tool)
           if (target_tools.key?(name) || reserved.key?(name)) && !server.name.to_s.empty?
             name = "#{server.name}_#{name}"
           end
-          add_tool(target_tools, tool, name, reserved)
+          add_tool(target_tools, tool, name, reserved, reservation)
         end
 
         def tool_lines(entry)
@@ -214,16 +242,9 @@ module RubyLLM
         end
 
         def param_lines(tool)
-          schema = tool.parameters_schema || {}
-          properties = schema["properties"] || {}
-          required = schema["required"] || []
-
-          properties.filter_map do |param, spec|
-            spec ||= {}
-            status = required.include?(param) ? "required" : "optional"
-            line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
-            description = spec["description"].to_s
-            line += " — #{description}" unless description.empty?
+          parameter_specs(tool).map do |spec|
+            line = "- `#{spec[:name]}` (#{spec[:type]}, #{spec[:required] ? 'required' : 'optional'})"
+            line += " — #{spec[:description]}" unless spec[:description].empty?
             line
           end
         end

data/lib/ruby_llm/code_mode.rb

@@ -5,7 +5,7 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.4.3"
+    VERSION = "0.5.1"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
@@ -25,10 +25,16 @@ module RubyLLM
     ToolEntry = Struct.new(:name, :tool, keyword_init: true)
 
     McpEntry = Struct.new(:name, :mcp, :instructions, keyword_init: true)
+
+    # Settings of the on-demand tool catalog (see .tool_catalog): how many
+    # results one search returns and how many characters of each tool's
+    # description the compact listing shows.
+    ToolCatalog = Struct.new(:search_limit, :preview_chars, keyword_init: true)
   end
 end
 
 require_relative "code_mode/description"
+require_relative "code_mode/catalog"
 require_relative "code_mode/registry"
 require_relative "code_mode/dsl"
 require_relative "code_mode/instance_methods"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-code_mode
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.1
 platform: ruby
 authors:
 - Juneira
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
 - !ruby/object:Gem::Dependency
   name: security_box
   requirement: !ruby/object:Gem::Requirement
@@ -78,6 +78,7 @@ files:
 - LICENSE
 - README.md
 - lib/ruby_llm/code_mode.rb
+- lib/ruby_llm/code_mode/catalog.rb
 - lib/ruby_llm/code_mode/description.rb
 - lib/ruby_llm/code_mode/dsl.rb
 - lib/ruby_llm/code_mode/instance_methods.rb