API GuidesResponses API

Tool Calling

Function calling and tool integration with the Responses API Beta
Beta API

This API is in beta stage and may have breaking changes.

The Responses API Beta supports comprehensive tool calling capabilities, allowing models to call functions, execute tools in parallel, and handle complex multi-step workflows.

Basic Tool Definition

Define tools using the OpenAI function calling format:

Tool Choice Options

Control when and how tools are called:

Tool ChoiceDescription
autoModel decides whether to call tools
noneModel will not call any tools
{type: 'function', name: 'tool_name'}Force specific tool call

Force Specific Tool

Disable Tool Calling

Multiple Tools

Define multiple tools for complex workflows:

Parallel Tool Calls

The API supports parallel execution of multiple tools:

Tool Call Response

When tools are called, the response includes function call information:

Tool Responses in Conversation

Include tool responses in follow-up requests:

Required Field

The id field is required for function_call_output objects when including tool responses in conversation history.

Streaming Tool Calls

Monitor tool calls in real-time with streaming:

Tool Validation

Ensure tool calls have proper structure:

Required fields:

  • type: Always “function_call”
  • id: Unique identifier for the function call object
  • name: Function name matching tool definition
  • arguments: Valid JSON string with function parameters
  • call_id: Unique identifier for the call

Best Practices

  1. Clear descriptions: Provide detailed function descriptions and parameter explanations
  2. Proper schemas: Use valid JSON Schema for parameters
  3. Error handling: Handle cases where tools might not be called
  4. Parallel execution: Design tools to work independently when possible
  5. Conversation flow: Include tool responses in follow-up requests for context

Next Steps