beta_tool_choice_options: "none" or "auto" or "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.

"none"
"auto"
"required"
beta_tool_choice_allowed: object { mode, tools, type }

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

mode: "auto" or "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.

"auto"
"required"
tools: array of map[unknown]

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.

beta_tool_choice_types: object { type }

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

type: "file_search" or "web_search_preview" or "computer" or 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
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
beta_tool_choice_function: object { 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.

beta_tool_choice_mcp: object { 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: optional string

The name of the tool to call on the server.

beta_tool_choice_custom: object { 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.

BetaSpecificProgrammaticToolCallingParam: object { type }
beta_tool_choice_apply_patch: object { 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.

beta_tool_choice_shell: object { type }

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

type: "shell"

The tool to call. Always shell.