Enum ResponsesToolChoice 

pub enum ResponsesToolChoice {
    Options(ToolChoiceOptions),
    Types {
        tool_type: BuiltInToolChoiceType,
    },
    Function(ResponsesFunctionToolChoice),
    AllowedTools {
        tool_type: AllowedToolsToolChoiceTag,
        mode: String,
        tools: Vec<ToolReference>,
    },
    Mcp {
        tool_type: McpToolChoiceTag,
        server_label: String,
        name: Option<String>,
    },
    Custom {
        tool_type: CustomToolChoiceTag,
        name: String,
    },
    ApplyPatch {
        tool_type: ApplyPatchToolChoiceTag,
    },
    Shell {
        tool_type: ShellToolChoiceTag,
    },
}

tool_choice accepted on the Responses API (POST /v1/responses).

The Responses spec enumerates eight concrete wire shapes, each with a distinct discriminator — see ResponsesToolChoice variants below. Deserialised via #[serde(untagged)] because the outermost JSON is either a bare string (Options) or an object whose "type" picks the variant.

Each object variant pins the discriminator through a single-value tag enum (FunctionToolChoiceTag, etc.) so serde cannot match a payload whose type does not belong to that variant. Without the tag pinning, the #[serde(untagged)] enum would accept any object shape that happened to fit the field set of an earlier variant.

This type deliberately does NOT live in common.rs: Chat Completions has its own ToolChoice with a different Function wire shape (nested {"function": {"name": ...}}) and does not accept the Types / Mcp / Custom / ApplyPatch / Shell variants at all. Sharing one enum across both APIs would silently accept spec-invalid payloads on /v1/chat/completions.

Variants

Options(ToolChoiceOptions)

"none" | "auto" | "required".

Types

{"type": "file_search" | "web_search" | "web_search_preview" | "web_search_preview_2025_03_11" | "image_generation" | "computer_use_preview" | "code_interpreter"} — select a built-in hosted tool by type alone (no additional payload).

Fields

tool_type: BuiltInToolChoiceType

Function(ResponsesFunctionToolChoice)

{"type": "function", "name": "..."} — Responses spec flat shape.

Accepts both the spec-canonical flat wire shape and the legacy Chat-style nested shape ({"type": "function", "function": {"name": "..."}}) on deserialize to preserve backward compatibility with smg clients written against the pre-split shared ToolChoice type. Always serializes as the canonical flat shape per the OpenAI Responses spec — Postel’s law: liberal on input, conservative on output.

The nested legacy shape is gated behind a custom Deserialize impl on ResponsesFunctionToolChoice; the untagged outer enum still pins the "type": "function" discriminator via FunctionToolChoiceTag so payloads without that tag cannot reach this variant.

AllowedTools

{"type": "allowed_tools", "mode": "auto"|"required", "tools": [...]}.

tools is an array of ToolReference items — the same type reused from Chat’s Allowed Tools payload because the Responses spec also allows function / mcp / file_search / web_search_preview / computer_use_preview / code_interpreter / image_generation entries.

Fields

tool_type: AllowedToolsToolChoiceTag

mode: String

"auto" or "required". Validated at request-normalisation time (see validate_tool_choice_with_tools).

tools: Vec<ToolReference>

Mcp

{"type": "mcp", "server_label": "...", "name"?: "..."} — force routing to a specific MCP server, optionally pinning a tool name.

Fields

tool_type: McpToolChoiceTag

server_label: String

name: Option<String>

Custom

{"type": "custom", "name": "..."} — pin a user-registered custom tool by name.

Fields

tool_type: CustomToolChoiceTag

name: String

ApplyPatch

{"type": "apply_patch"} — force the built-in apply_patch tool.

Fields

tool_type: ApplyPatchToolChoiceTag

Shell

{"type": "shell"} — force the built-in shell tool.

Fields

tool_type: ShellToolChoiceTag

Implementations

impl ResponsesToolChoice

pub fn serialize_to_string(tool_choice: Option<&ResponsesToolChoice>) -> String

Serialize tool_choice to string for ResponsesResponse payloads.

Returns the JSON-serialized tool_choice or "auto" as default.

pub fn function_name(&self) -> Option<&str>

Return the pinned function name for the Function variant, regardless of which wire shape (spec-flat name or legacy nested function.name) was used at deserialize time. None for any non-Function variant.

Consumers that need to project / validate the function name should go through this accessor rather than pattern-matching so future wire shapes can be added without touching call sites.

pub fn to_chat_tool_choice(&self) -> ChatToolChoice

Project the Responses-level tool_choice onto a Chat Completions tool_choice when a Responses request is being routed through the Chat Completions gRPC pipeline.

Mapping rules:

• Options(None|Auto|Required) → ChatToolChoice::Value(...) — shared semantics.
• Function { name } → ChatToolChoice::Function { nested name } — shape translation (flat Responses → nested Chat wire form).
• AllowedTools { mode, tools } → ChatToolChoice::AllowedTools {...}.
• Hosted / custom / apply_patch / shell / mcp — Chat Completions has no equivalent spec variant; fall back to Auto so the downstream chat backend still runs with tool-calling enabled.

Trait Implementations

impl Clone for ResponsesToolChoice

fn clone(&self) -> ResponsesToolChoice

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ResponsesToolChoice

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ResponsesToolChoice

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ResponsesToolChoice

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for ResponsesToolChoice

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for ResponsesToolChoice

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.