OpenAI Tool Call Schema¶

This page contains the API reference for tool and tool choice schema models used by builtin structural tag APIs.

class xgrammar.openai_tool_call_schema.FunctionDefinition(*, name: str, description: Optional[str] = None, parameters: Optional[Dict[str, Any]] = None, strict: Optional[bool] = None)[source]¶

Bases: BaseModel

A JSON-Schema-based function definition.

Corresponds to openai.types.shared_params.FunctionDefinition.

In Chat Completions this object is nested under tools[].function. In the Responses API, the function tool fields are flat on the tool object itself and correspond to openai.types.responses.FunctionToolParam.

field name: str [Required]¶

The name of the function to be called.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

field description: Optional[str] = None¶: A description of what the function does, used by the model to choose when and how to call the function.

field parameters: Optional[Dict[str, Any]] = None¶

The parameters the functions accepts, described as a JSON Schema object.

If omitted or set to None, the generated function arguments will be unconstrained.

field strict: Optional[bool] = None¶

Whether to enable strict schema adherence when generating the function call.

If set to true, the model will follow the exact schema defined in the parameters field.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class xgrammar.openai_tool_call_schema.FunctionToolParam(*, type: Literal['function'] = 'function', function: FunctionDefinition)[source]¶

Bases: BaseModel

A function tool that can be used to generate a response.

Corresponds to openai.types.chat.ChatCompletionFunctionToolParam.

Chat Completions shape:

{"type": "function", "function": {"name": "...", "parameters": {...}}}

Responses API shape is flat and corresponds to openai.types.responses.FunctionToolParam:

{"type": "function", "name": "...", "parameters": {...}}

field type: Literal['function'] = 'function'¶: The type of the tool. Currently, only function is supported.

field function: FunctionDefinition [Required]¶: The function definition.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class xgrammar.openai_tool_call_schema.BuiltinToolParam(*, type: str, name: Optional[str] = None, parameters: Optional[Dict[str, Any]] = None)[source]¶

Bases: BaseModel

A builtin tool whose output should be constrained.

This mirrors hosted/server tool declarations used by APIs such as OpenAI Responses or Anthropic Messages. type is the provider-facing builtin tool type. name is the tool name that appears in the model output; when omitted, callers should use type as the output name. parameters is the JSON schema required by XGrammar and serving engines for constrained decoding.

field type: str [Required]¶: The provider-facing builtin tool type.

field name: Optional[str] = None¶

The output tool name for model. XGrammar-specific field.

Used to constrain the tool name. Use this when the model emits a tool name that differs from the provider type. For example, an OpenAI-style web_search_preview builtin may be emitted as browser.search by a Harmony-style model. Defaults to type when omitted.

field parameters: Optional[Dict[str, Any]] = None¶

Argument schema for the builtin tool. XGrammar-specific field.

Hosted/server tool APIs often do not require users to provide this schema, but XGrammar and serving engines need it to constrain the arguments emitted by the model.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

xgrammar.openai_tool_call_schema.ToolParam(*args, **kwargs)¶

A function or builtin tool accepted by builtin structural tag APIs.

alias of Union[FunctionToolParam, BuiltinToolParam]

class xgrammar.openai_tool_call_schema.NamedToolChoiceParam(*, type: Literal['function'] = 'function', function: NamedToolChoiceFunction)[source]¶

Bases: BaseModel

Specifies a tool the model should use.

Use to force the model to call a specific function.

Corresponds to openai.types.chat.ChatCompletionNamedToolChoiceParam.

Chat Completions shape:

{"type": "function", "function": {"name": "..."}}

Responses API shape is flat and corresponds to openai.types.responses.ToolChoiceFunctionParam:

{"type": "function", "name": "..."}

field type: Literal['function'] = 'function'¶: For function calling, the type is always function.

field function: NamedToolChoiceFunction [Required]¶: The function to call.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class xgrammar.openai_tool_call_schema.BuiltinToolChoiceParam(*, type: str, name: Optional[str] = None)[source]¶

Bases: BaseModel

Specifies a builtin tool the model should use.

type matches the builtin tool type in tools. Matching is based on type; name is accepted for API compatibility but is not used for matching.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field type: str [Required]¶: The builtin tool type.

field name: Optional[str] = None¶: Optional model-output tool name. Builtin choices are matched by type.

class xgrammar.openai_tool_call_schema.AllowedToolChoiceParam(*, type: Literal['allowed_tools'] = 'allowed_tools', allowed_tools: AllowedToolsParam)[source]¶

Bases: BaseModel

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

Corresponds to openai.types.chat.ChatCompletionAllowedToolChoiceParam.

Chat Completions shape:

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

Responses API shape is flat and corresponds to openai.types.responses.ToolChoiceAllowedParam:

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

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field type: Literal['allowed_tools'] = 'allowed_tools'¶: Allowed tool configuration type. Always allowed_tools.

field allowed_tools: AllowedToolsParam [Required]¶: Constrains the tools available to the model to a pre-defined set.

xgrammar.openai_tool_call_schema.ToolChoiceOptionParam(*args, **kwargs)¶

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.

Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.

Corresponds to openai.types.chat.ChatCompletionToolChoiceOptionParam.

alias of Union[Literal[‘none’, ‘auto’, ‘required’], NamedToolChoiceParam, AllowedToolChoiceParam, BuiltinToolChoiceParam]