class RubyLLM::Chat

Creates a chat with model:, or with the configured default model when model: is nil. Most code calls RubyLLM.chat instead.

A model is identified by its name, an optional provider:, and an optional protocol:. Pass provider: to disambiguate models available from several providers, and protocol: to override the wire protocol the provider would otherwise pick for the model. With assume_model_exists: true the registry lookup is skipped, which requires provider:. Pass a Context as context: to use its configuration instead of the global one.

Appends a message to the conversation and returns it as a Message. Accepts a Message, an attribute Hash, or a record responding to to_llm.

chat.add_message(role: :user, content: "What's the capital of France?")

Registers a callback that receives each queued message as it joins the conversation: the user Message it became, then the QueuedMessage. It runs in the loop’s thread, before the model is asked to answer it. Returns self.

chat.after_dequeue { |message, queued| puts "Joined: #{message.content}" }

Registers a callback that receives the Fallback attempt once it has succeeded or failed. Returns self.

Registers a callback that receives each StoredFile the conversation writes to the chat’s FileStore (see with_file_store): attachments as they are kept, long tool results, and the files tools and code write.

Registers a callback that receives each assistant response and each tool result message once it has been appended. Returns self.

chat.after_message { |message| puts message.content }

Registers a callback that receives each QueuedMessage once queue has added it. It runs in the thread that called queue. Returns self.

chat.after_queue { |queued| puts "Queued: #{queued.content}" }

Registers a callback that receives the ToolCall and a Progress each time a running local tool reports what it is doing, with Tool#progress or, for MCP tools, through the server’s progress notifications. Returns self.

chat.after_tool_progress do |tool_call, progress|
  puts "#{tool_call.name}: #{progress.message}"
end

The callback runs in the thread or fiber that reports, before the tool’s result. On Ruby 3.2 and later, that includes threads and fibers the tool starts. With concurrent tool execution, callbacks for different tool calls can run at the same time.

Registers a callback that receives each local tool’s result after execution. Returns self.

Registers a callback that receives each QueuedMessage unqueue takes out of the queue. It runs in the thread that called unqueue. Returns self.

Answers request, an MCP::InputRequest from pending_inputs, with values for a form, or none to accept a URL request. The next complete resumes the call once its requests are settled. Returns self.

Records approval for tool_call, a ToolCall or its id, so the next complete or run_tools executes a local tool or records permission for the provider to execute a remote tool on the next request. Returns self.

chat.approve(tool_call)
chat.complete

With remember: true, later calls to the same tool run without asking for the rest of the chat.

chat.approve(tool_call, remember: true)

A run_code call that asks for another sandbox is approved one call at a time: passing remember: true for it raises ArgumentError, and the approval never applies to another call.

Adds message as a user message and runs the conversation loop, executing tools until the model answers or a call needs approval. Returns the latest assistant Message; check waiting? before treating it as a final answer. Attach files with with:. An MCP::Prompt adds its messages instead. Messages still in the queue (see queue) join the conversation first, in order. A given block receives streamed Chunk objects as they arrive.

String attachments read local paths or fetch URLs. Only pass trusted, authorized sources; validate user uploads before calling this method. See Attachment.new.

chat.ask "What's the best way to learn Ruby?"
chat.ask "What's in this image?", with: "ruby_conf.jpg"
chat.ask "Analyze these files", with: ["diagram.png", "report.pdf"]
chat.ask("Tell me a story") { |chunk| print chunk.content }
chat.ask github.prompt(:code_review, code: diff)

Stages message as a user message without requesting a completion, leaving the chat ready for complete, a single step, or a provider-side batch via RubyLLM.batch. Accepts attachments with with: like ask. Returns self.

chats = tickets.map { |t| RubyLLM.chat.ask_later(t.body) }
RubyLLM.batch(chats)

Every message still in the queue (see queue) joins the conversation first, in order, whether it steers or not.

Raises PendingToolCallsError while the last response has unanswered tool calls: finish the round first, recording approve or deny decisions for calls that require approval.

Returns whether the conversation can make no progress without an approval decision: every remaining pending tool call requires approval and has none recorded, or waits on input. While true, complete returns without executing them; record decisions with approve or deny, then call complete again. Tool calls that need no approval still execute before the loop pauses.

Consults each pending tool’s approval resolver when one is declared, so resolvers must be idempotent reads.

Returns whether the conversation can make no progress until the user answers an MCP server: every remaining pending tool call waits on input or an approval decision, and at least one waits on input.

Returns whether the conversation can make no progress until tasks finish: every remaining pending tool call waits on a Task, input, or an approval decision, and at least one waits on a Task. complete resumes the calls again.

chat.ask "Render the quarterly report"
chat.awaiting_tasks?  # => true
sleep chat.pending_tasks.first.poll_interval
chat.complete

Registers a callback that receives the Fallback attempt after the current model fails and before the fallback model is tried. Returns self.

Registers a callback that runs before each assistant response or tool result is appended to the conversation. Callbacks are additive: every registered block runs. Returns self.

Registers a callback that receives the fully rendered request payload before it is sent and may mutate it in place. Runs after all RubyLLM formatting and with_provider_options merging. Returns self.

chat.before_request { |payload| logger.debug payload }

Registers a callback that receives each local ToolCall before the tool executes. Returns self.

chat.before_tool_call { |tool_call| puts tool_call.name }

Marks the latest message as an explicit prompt cache boundary, asking the provider to cache everything up to this point. Pass ttl: to give this boundary its own cache lifetime, as Message#cache_until_here describes. Returns self.

chat.with_instructions(policy).cache_until_here(ttl: "1h")

Raises ArgumentError if the chat has no messages.

Cancels the current in-flight chat operation. Every cancellation checkpoint raises CancelledError until the operation ends, so tool calls running concurrently all stop, and the flag is cleared then so the chat can be reused. The tasks that pending tool calls wait on are cancelled then too; see pending_tasks.

Returns whether this in-memory chat has been marked for cancellation.

Compacts the conversation’s model context and returns an assistant Message. The message can have empty text and carries the provider’s compacted context internally. Every earlier message remains in messages, including on persisted Rails chats.

chat.ask "Remember these project requirements..."
chat.compact
chat.ask "Which requirement should we implement first?"

Uses the current instructions, headers, and request hooks. Records reported usage and runs the normal message callbacks. Raises Error when the provider has no manual compaction endpoint, and PendingToolCallsError until pending tool calls have been answered.

Runs the conversation loop until complete? or waiting? is true. Returns the last conversation Message, or nil for an empty chat. While the chat is waiting?, returns the assistant Message that holds the pending tool calls, even after other tools in the round have run. Used after ask_later; ask calls complete for you.

When a pending tool call requires approval and no decision has been recorded, or waits on input for an MCP server, the loop pauses. Record approve, deny, answer, or decline decisions, then call complete again to continue. A tool call that returns a Task pauses the loop too, and each complete resumes it once with Tool#resume, without waiting, and continues once it has a result. For an MCP tool, that checks on its MCP::Task.

The first time the loop could ask the model, every message in the queue joins the conversation, in order. After that, only messages that steer join, after each round of tool results and after the answer, so the turn goes on until the model has answered them. Messages queued with steer: false wait for the next complete. See queue.

Returns whether the chat has no pending response or tool execution: nothing is staged, or the model answered without requesting tools, and no queued message steers the turn. Messages queued with steer: false don’t count, so the chat is complete while they wait for the next complete.

Converts attachments the current protocol cannot render with the given block. Returns self. The block receives an Attachment and returns a replacement Attachment, or nil to keep the existing error. Blocks run in registration order until one returns a replacement. The transcript keeps the original file, even when the model changes. The chat converts each attachment once and reuses the replacement, and its upload, on later requests.

chat.convert_unsupported_attachments do |attachment|
  text = TextExtraction.call(attachment)
  Attachment.new(StringIO.new(text), filename: 'extracted.txt') if text
end

Returns a Cost aggregating every provider attempt this chat has made, including retries and attempts that produced no message.

chat.cost.total

Counts input tokens for the conversation, including instructions, function tools, structured output, thinking, and attachments. Pass message to include it as a staged user message without mutating the chat. Returns an Integer.

chat.with_instructions("Be terse.").with_tools(Weather)
chat.count_tokens("What's the weather in Berlin?")

Provider tools, provider_options, compaction, and before_request hooks are not included. Raises Error when the provider has no token counting endpoint.

Declines request, an MCP::InputRequest from pending_inputs. Returns self.

Returns the tools whose definitions stay out of the model’s context until the provider’s tool search loads them, as a Hash like tools. Providers without tool search receive them as ordinary tools.

chat.with_tools(Weather).with_mcp(GitHub, defer: true)
chat.deferred_tools.keys # => [:search_issues, :create_issue, ...]

Records denial for tool_call, a ToolCall or its id. The next complete or run_tools appends a structured denial result instead of executing a local tool, or sends a refusal for a remote tool on the next request. The model continues from there. Returns self.

Yields each Message in the conversation. Returns an Enumerator when no block is given. Chat includes Enumerable, so the usual collection methods are available.

Returns the FileStore attached with with_file_store, or nil without one.

chat.file_store.list
chat.file_store.read("notes/plan.md")

Requests one completion from the model, appends the response to the conversation, and returns it as a Message. Honors the fallbacks configured with with_fallbacks. A given block receives streamed Chunk objects. Tool calls in the response are not executed; that is run_tools.

Replaces the conversation with new_messages, coercing each element into a Message. Accepts Message objects, attribute Hashes, and records responding to to_llm.

Returns the tool calls from the latest response that require approval and have no recorded decision, as an array of ToolCall objects. Pairs with approve and deny. ToolCall#remote? identifies provider-executed calls.

chat.pending_approvals.each { |tool_call| puts tool_call.name }
chat.approve(chat.pending_approvals.first)

Returns the unanswered requests for input that paused MCP tool calls, as MCP::InputRequest objects. Settle each with answer or decline, then call complete to resume the calls.

chat.pending_inputs.each { |request| puts request.message }
chat.answer(chat.pending_inputs.first, environment: "staging")

Returns the Task objects that tool calls wait on, as they were when the chat last checked, with an MCP::Task for each MCP tool call. Task#refresh checks on one without resuming the chat; complete resumes every call with Tool#resume. A task that is Task#input_required? waits on a person, so there is no point in checking on it before they act.

chat.pending_tasks.each { |task| puts "#{task.tool_call.name}: #{task.status_message}" }

Adds message to the queue: a user message that waits outside the conversation until the loop takes it. Call it at any time, from any thread, even while complete runs in another one. Attach files with with:, as with ask. Returns the QueuedMessage.

chat.queue "Use the EU file instead"
chat.queue "Then email it to me", steer: false
chat.queue "Check this one too", with: "q3.pdf", owner: current_user

A message that steers, the default, joins the turn that is running: after the next round of tool results, or once the model finishes its answer, which then goes on to answer it too. Pass steer: false to wait for the turn to end instead: complete returns, the chat is complete?, and the next ask, ask_later, complete, or step takes the message. Steering messages can join before waiting ones queued earlier. Messages that join together become separate user messages, oldest first.

Nothing is taken while the chat is waiting?, and cancel leaves the queue as it is. Queueing never runs the loop: when nothing is running, call complete. owner is stored with the message and handed back on it without RubyLLM interpreting it.

Returns the messages waiting in the queue, as QueuedMessage objects, oldest first.

Returns the request payload this chat would send to the provider for its next completion, with before_request hooks applied. Useful for inspecting and testing request output.

Executes the tool calls pending in the latest response and appends their result messages, without asking the model to respond. Tool calls that already have results are skipped, so a chat reloaded mid-round resumes with only the remaining tools. Calls whose tool was declared with Tool.requires_approval only execute once approve records a decision; denied calls receive a structured denial result, and undecided calls stay pending. Does nothing when no tool calls are pending. Calls paused on a Task resume once. The chat is then ready for the next generate, or the next batch round. Returns self.

Advances the conversation by one move: runs the pending tool calls if any are unanswered, otherwise generates the next response. Returns the Message that move produced, and nil once there is nothing left to do or the chat is waiting?.

Unless tool calls are pending, every message in the queue (see queue) joins the conversation before the model is asked, whether it steers or not.

Returns the thinking options resolved for the current model, or nil when thinking was not configured or needs no provider control. When the model registry has no thinking controls for the model, returns the request itself, { enabled: true } or { enabled: false }; the request then raises ArgumentError.

Returns token usage aggregated across every provider attempt this chat has made, including retries and attempts that produced no message.

chat.tokens.input

Returns the choice, calls, and concurrency set with with_tool_options, with nil for anything left at the default.

Returns the tools the model can call, as a Hash of tool name Symbols to Tool instances: those registered with with_tools and those of the MCP servers connected with with_mcp. MCP tools that only the UI of an MCP App may call are left out; see MCP::Tool#visibility.

Raises ArgumentError when two tools share a name.

Takes queued, a QueuedMessage or its id, out of the queue before the loop takes it. Returns true, or false when it is no longer queued: the loop took it into the conversation, or it was unqueued already.

chat.unqueue(queued) # => true

Returns whether the conversation can’t continue until something outside it happens: every remaining pending tool call waits on an approval decision, an answer to an MCP input request, a Task, or a run in another process. complete stops here, and awaiting_approval?, awaiting_input?, and awaiting_tasks? tell what it waits on. Stop a loop you drive with step here too:

chat.step until chat.complete? || chat.waiting?

Enables provider prompt caching. With no arguments the provider’s default behavior applies; options such as ttl: apply where supported. Pass id: with a CachedContent (or its name) from RubyLLM.cache to attach an explicit content cache. Pass false to stop RubyLLM from sending cache controls or rendering explicit cache boundaries. A provider may still cache prompts implicitly. Passing nil raises ArgumentError. Returns self.

chat.with_caching
chat.with_caching(ttl: "1h")
chat.with_caching(id: cache)
chat.with_caching(false)

Enables document citations, so the model backs its claims with quotes from attached files. Pass false to disable. Passing nil raises ArgumentError. Returns self.

chat.with_citations
response = chat.ask "Who created Ruby?", with: "facts.txt"
response.citations.each { |citation| puts citation.cited_text }

Lets the model run code in a Sandbox. The model gets one tool, run_code, that runs Ruby, Python, JavaScript, or a shell script in a fresh run directory, with read-only copies of the conversation’s files, and returns the output and every file the code writes there as attachments on the tool result. With with_file_store, runs work with the chat’s files instead: in the store’s folder when it has one (FileStore#local_root), otherwise on copies of the files the model names, with what the code writes saved back. The options are:

sandbox

the sandbox every call runs in. Default: Configuration#sandbox.

escalate_to

sandboxes the model may ask for, one call at a time, as an Array named after their classes (WorkspaceSandbox is workspace) or a Hash of names to sandboxes. Each call that asks waits for approve.

languages

the languages the model may use, from :ruby, :python, :javascript, and :shell. Default: Ruby and shell, plus Python and JavaScript when their packages are declared.

gems

gems installed once and available to every Ruby run.

python

Python packages installed once and available to every Python run.

npm

npm packages installed once, without their install scripts, and available to every JavaScript run.

gem_home

a GEM_HOME with gems already installed, used instead of gems.

virtualenv

a Python virtualenv with packages already installed, used instead of python.

node_modules

a node_modules directory with packages already installed, used instead of npm.

mounts

directories mounted read-only in each run directory, keyed by their path there, or a Proc called before each run that returns them.

Accepts keywords or an options Hash. Pass false to disable it. Passing nil raises ArgumentError. Returns self.

chat.with_code_execution
chat.with_code_execution(gems: %w[prawn], python: %w[pandas matplotlib])
chat.with_code_execution(sandbox: ReadOnlySandbox, escalate_to: [WorkspaceSandbox, OnlineSandbox])
chat.with_code_execution(mounts: { "templates" => "app/templates/reports" })
chat.with_code_execution(false)

Raises ConfigurationError when no sandbox is configured. Code never runs outside a sandbox. To run code on the provider’s servers instead, use with_provider_tools(:code_execution).

Enables provider-side context compaction, so a long conversation keeps going instead of overflowing the context window. The provider condenses the earlier turns itself and returns a block that RubyLLM replays on later requests. With no arguments the provider’s own defaults apply. The options are provider-neutral:

at

the input-token count that triggers compaction.

instructions

a custom prompt for the summary the provider writes.

pause_after

end the turn once compaction runs, instead of continuing straight into the answer.

Each provider applies the options it supports. Unsupported options are ignored with a debug log. Pass false to disable; passing nil raises ArgumentError. Returns self.

chat.with_compaction
chat.with_compaction(at: 50_000)
chat.with_compaction(at: 100_000, instructions: "Keep every decision.")
chat.with_compaction(false)

What a provider does when the threshold is crossed differs. Anthropic and OpenAI summarize the compacted span into an opaque block that replaces it; OpenRouter drops messages from the middle of the conversation instead, and has no threshold of its own.

Rebinds the chat to context, a Context built with RubyLLM.context, so subsequent requests use its configuration. Pass nil to return to the global RubyLLM.config. Returns self.

Identifies the end user behind the conversation for the provider’s abuse monitoring. Providers without an equivalent field omit it. Pass nil to remove it. Returns self.

chat.with_end_user("user-123").ask "Hello"

The value is sent as given, so use an opaque id such as a hash of your user id, never personal data.

Sets fallback models to try, in order, when generation fails. on: selects the error classes that trigger a fallback; the default covers transient provider and network errors. Cancelling the chat never triggers a fallback, and neither does another process taking over a persisted chat or an error your streaming block raises. Pass nil to remove all fallbacks and restore the default error classes. Returns self.

chat.with_fallbacks("gpt-4.1-mini", "claude-haiku-4-5")
chat.with_fallbacks(nil)

Attaches store, a FileStore, to the chat and gives the model five tools to work with it: list_files, read_file, search_files, write_file, and edit_file. Files stop filling the conversation:

• Every attachment is kept in the store. The model sees the files attached to the latest question, and those it opens with read_file, in full until the next question; after that, and for files other tools return, it sees one line naming the file.

• A tool result longer than spill_to_file characters is saved under results/, and the model gets its start and the file’s path.

• With with_code_execution, code runs in the store’s folder when it has one, such as FileStore::Directory, changing the files in place. With other stores, each run copies in the files the model names, and what the code writes is saved back to the store.

Without store, the chat gets a new FileStore::Memory, or for a persisted chat, its files in Active Storage. spill_to_file is the characters a tool result may have before it is saved as a file, or false to send every result whole; tools can set their own with Tool.spill_to_file. Default: 10,000.

Pass nil to remove the store and its tools. Returns self.

chat.with_file_store
chat.with_file_store(RubyLLM.file_store.directory("tmp/chats/42"))
chat.with_file_store(spill_to_file: 20_000)
chat.with_file_store(nil)

Text files are read as text; register converters, such as the OCR converter for PDFs and images, in Configuration#file_converters to read more.

Sets extra HTTP headers sent with completion requests, replacing any previously set headers; nil clears them. Returns self.

chat.with_headers('anthropic-beta' => 'fine-grained-tool-streaming-2025-05-14')

Sets the system instructions for the conversation, replacing any existing system messages. With append: true the instructions are added alongside the existing ones. With cache_until_here: true the instruction becomes an explicit prompt cache boundary; pass cache_until_here: { ttl: "1h" } to give that boundary its own lifetime, as Message#cache_until_here describes. Pass nil to remove all system instructions. Returns self.

chat.with_instructions "You are a helpful Ruby tutor."
chat.with_instructions "Use exactly one short paragraph.", append: true
chat.with_instructions policy, cache_until_here: { ttl: "1h" }
chat.with_instructions nil

Caps the number of tokens the model may generate. Pass nil to remove the limit. Returns self.

chat.with_max_output_tokens(1000)

Connects MCP servers, each an MCP instance or class, and gives the model their tools. The servers are contacted when the chat first needs their tools. Pass nil to disconnect them all. Returns self.

The chat closes the servers it built from a class when it disconnects them, or when another server takes their name. Instances you pass in stay open: close them with MCP#close.

chat.with_mcp(Linear.new(user: current_user), Files)
chat.mcp.linear

Pass defer: true to keep every tool of these servers out of the model’s context until the provider’s tool search loads it, or defer: false to offer them up front despite MCP.defer. See deferred_tools.

chat.with_mcp(GitHub, defer: true)

Switches the chat to model_id and its provider. Pass provider: to disambiguate, and assume_model_exists: true to skip registry validation for custom or private models. Pass nil to return to the configured default model. Returns self.

protocol: overrides the wire protocol the provider would pick for the model, such as :responses or :chat_completions for OpenAI. It stays nil by default, meaning the provider chooses the protocol for each request. A bare with_model resets the override to nil, just as it re-resolves the provider from the model.

Raises ModelNotFoundError if model_id is not in the registry and assume_model_exists: is false.

chat.with_model('claude-sonnet-5')
chat.with_model('gpt-6.1-sol', protocol: :chat_completions)

Sets options in the provider’s request vocabulary, merged into the request payload as-is and overriding RubyLLM’s defaults. Replaces any previously set provider options; nil clears them. Returns self.

chat.with_provider_options(service_tier: "flex")

Enables tools that run on the provider’s servers, such as web search or code execution. Accepts portable alias Symbols, alias-with-options keywords whose options use the provider’s own vocabulary, and raw Hashes passed to the provider verbatim, so provider tools RubyLLM has no alias for yet work without a gem update. Entries add to any tools enabled earlier. Enabling an alias again replaces its options, and an identical raw Hash or MCP server is not repeated, so a chat sends each tool once. Pass nil to clear them all. Returns self.

chat.with_provider_tools(:web_search)
chat.with_provider_tools(:web_search, :code_execution)
chat.with_provider_tools(web_search: { allowed_domains: ["ruby-lang.org"] })
chat.with_provider_tools({ type: "web_search_20260318", name: "web_search" })

The tool steps the model ran come back on Message#server_tool_calls, citations from search tools on Message#citations, and per-use billing counters on message.tokens.server_tool_use.

Raises UnsupportedServerToolError at request time when the provider has no provider-tool support or does not define a requested alias.

Sets the schema for structured output. Accepts a JSON Schema Hash, a Schematist::Schema class or instance, or any object responding to to_json_schema. Returns self.

class PersonSchema < Schematist::Schema
  string :name
  integer :age
end

chat.with_schema(PersonSchema)
response = chat.ask("Generate a person named Alice who is 30 years old")
response.parsed # => {"name" => "Alice", "age" => 30}

Pass nil to remove the schema, returning the chat to plain text responses.

Gives the model skills: folders of instructions, scripts, and files in the open Agent Skills format. Called bare or with true, adds every skill directly under Skill.roots, app/skills by default. Symbols name folders under the roots, and Strings and Pathnames are paths to skill folders. Pass false to remove every skill. Passing nil raises ArgumentError. Returns self.

chat.with_skills
chat.with_skills(:invoices, :reports)
chat.with_skills(:invoices, "vendor/skills/pdf")
chat.with_skills(false)

Every request lists each skill’s name and description, and the model loads a skill’s instructions and files with its load_skill tool. With with_code_execution, each skill folder is mounted read-only in every run at skills/<name>/, so the model can run the skill’s scripts.

Raises SkillNotFoundError for a missing skill, InvalidSkillError for a SKILL.md that breaks the specification, and ArgumentError when two skills share a name.

Sets the sampling temperature for subsequent requests. Pass nil to return to the model’s default sampling behavior. Returns self.

chat.with_temperature(0.2)

Configures extended thinking for models that support it. With no arguments, RubyLLM uses the current model’s registered default. Pass false to disable thinking, or tune it with effort: (:low, :medium, :high, :none, or a provider-specific tier such as :minimal, :xhigh, or :max, passed through as-is), budget: (a token count), and display: (:summarized or :omitted, controlling whether providers that support it return readable thinking text). Accepts keywords or an options Hash. Passing nil raises ArgumentError. Returns self.

chat.with_thinking
chat.with_thinking(false)
chat.with_thinking(effort: :high)
chat.with_thinking(budget: 10_000)
chat.with_thinking(display: :summarized)

Configures how the model uses the registered tools. choice: constrains tool use to :auto, :none, :required, a tool name, or a Tool class. calls: limits how many tool calls one response may contain (:many or :one). concurrency: runs tool calls concurrently: true or :threads for threads, :fibers for fibers. An omitted option is left unchanged; passing nil explicitly resets that option (+concurrency: nil+ returns to the configured default). Returns self.

chat.with_tools(Weather, Search).with_tool_options(choice: :required)
chat.with_tool_options(calls: :one, concurrency: :threads)
chat.with_tool_options(choice: nil)

Registers tools, each a Tool class or instance, for the model to call. Configure how the model uses them with with_tool_options. Pass nil to remove all registered tools. Returns self.

chat.with_tools(Weather, Search)
chat.with_tools(Weather).with_tool_options(choice: :required)

Pass defer: true to keep the tools’ definitions out of the model’s context until the provider’s tool search loads the ones it needs, or defer: false to offer a tool declared with Tool.defer up front. See deferred_tools.

chat.with_tools(*Catalog.tools, defer: true)

To replace the registered tools, clear them first:

chat.with_tools(nil).with_tools(NewTool)