[FEATURE] Add built-in support for tool control parameters

[nwumnn]

Scope check

• This is core LLM communication (not application logic)
• This benefits most users (not just my use case)
• This can't be solved in application code with current RubyLLM
• I read the Contributing Guide

Due diligence

• I searched existing issues
• I checked the documentation

What problem does this solve?

Different LLM providers use different formats for tool control parameters (e.g., OpenAI's separate parameter, Anthropic's tool choice object). The current implementation requires provider-specific handling through with_params, making it difficult to switch providers.

Proposed solution

1. Add standardized tool_choice parameter. Support "auto", "required", "none", and specific tool selection.
2. Add boolean parameter to support allow/disallow parallel tool use.
3. Handle provider-specific format translation internally.

Why this belongs in RubyLLM

This aligns with RubyLLM's goal of providing a unified interface for LLM interactions while abstracting provider-specific implementations. These parameters need to be handled at the provider level because each provider has different format requirements.

[crmne]

That'd be cool. Do you want to take a crack at it? We could add a new parameter to .with_tool and .with_tools called choice that could accept either a falsy for no tools, :auto for auto (default), :required for required or any, or a specific tool to force that one.

[nwumnn]

I can give it a try. I was thinking about the API design and wondered if we might consider separate methods instead of adding parameters to .with_tool and .with_tools.
The reason is that if I only want to change the tool choice without modifying the tools themselves, it would be more convenient to have dedicated methods:

def with_tool_choice(choice)
  # choice: :auto (default), :required, :none, or specific tool name
end

def with_parallel_tools(enabled = true)
  # boolean to allow/disallow parallel tool calls  
end

But I'm happy to implement it either way you prefer.

[crmne]

Your use case can be still totally supported by .with_tools(nil, choice: :required, parallel: true). If you pass nil to .with_tools, nothing would change. Same thing would happen if you pass the same tools because they are indexed by name. https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/chat.rb#L63-L67

[nwumnn]

Thanks for the feedback. What about:

def with_tool_options(choice: nil, parallel: nil)
  # choice: :auto (default), :required, :none, or specific tool name
  # parallel: boolean to allow/disallow parallel tool calls
end

These are global settings that affect all tools, so adding them to .with_tool feels unintuitive. Also, I saw in #238 there's discussion about using .with_tool(nil) as an API for removing tools (similar to how with_schema(nil) works), so with_tools(nil, choice: :required) might be confusing.

[crmne]

Tool configuration and tool selection are one conceptual operation. Separating them creates artificial complexity.

# Common case stays beautiful
chat.with_tools(weather, calculator)

# Power when you need it
chat.with_tools(weather, calculator, choice: :required, parallel: false)

# Works with replace too
chat.with_tools(new_tool, replace: true)

Rails has, e.g., has_many :comments, dependent: :destroy not has_many :comments then with_association_options.

The happy path is configuration during tool selection.