One of the following:
BetaToolChoiceOptions = :none | :auto | :required

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

One of the following:
:none
:auto
:required
class BetaToolChoiceAllowed { mode, tools, type }

Constrains the tools available to the model to a pre-defined set.

mode: :auto | :required

Constrains the tools available to the model to a pre-defined set.

auto allows the model to pick from among the allowed tools and generate a message.

required requires the model to call one or more of the allowed tools.

One of the following:
:auto
:required
tools: Array[Hash[Symbol, untyped]]

A list of tool definitions that the model should be allowed to call.

For the Responses API, the list of tool definitions might look like:

[
  { "type": "function", "name": "get_weather" },
  { "type": "mcp", "server_label": "deepwiki" },
  { "type": "image_generation" }
]
type: :allowed_tools

Allowed tool configuration type. Always allowed_tools.

class BetaToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: :file_search | :web_search_preview | :computer | 5 more

The type of hosted tool the model should to use. Learn more about built-in tools.

Allowed values are:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation
One of the following:
:file_search
:web_search_preview
:computer
:computer_use_preview
:computer_use
:web_search_preview_2025_03_11
:image_generation
:code_interpreter
class BetaToolChoiceFunction { name, type }

Use this option to force the model to call a specific function.

name: String

The name of the function to call.

type: :function

For function calling, the type is always function.

class BetaToolChoiceMcp { server_label, type, name }

Use this option to force the model to call a specific tool on a remote MCP server.

server_label: String

The label of the MCP server to use.

type: :mcp

For MCP tools, the type is always mcp.

name: String

The name of the tool to call on the server.

class BetaToolChoiceCustom { name, type }

Use this option to force the model to call a specific custom tool.

name: String

The name of the custom tool to call.

type: :custom

For custom tool calling, the type is always custom.

class BetaSpecificProgrammaticToolCallingParam { type }
type: :programmatic_tool_calling

The tool to call. Always programmatic_tool_calling.

class BetaToolChoiceApplyPatch { type }

Forces the model to call the apply_patch tool when executing a tool call.

type: :apply_patch

The tool to call. Always apply_patch.

class BetaToolChoiceShell { type }

Forces the model to call the shell tool when a tool call is required.

type: :shell

The tool to call. Always shell.