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"
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<Record<string, 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.

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"
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.

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 | null

The name of the tool to call on the server.

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.

BetaSpecificProgrammaticToolCallingParam { type }
type: "programmatic_tool_calling"

The tool to call. Always programmatic_tool_calling.

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.

BetaToolChoiceShell { type }

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

type: "shell"

The tool to call. Always shell.