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

Tool calling with the Agent SDK

The OpenRouter agent SDK (@openrouter/agent for TypeScript, openrouter_agent for Python) runs the whole tool-calling loop for you. You define a tool with a typed input schema and an execute function. The SDK sends the tool definition to the Responses API, runs your function when the model calls it, returns the result to the model as a function_call_output, and gives you the final answer. You don’t build function_call and function_call_output items by hand or manage the follow-up requests. The sections below show that manual protocol in case you need raw HTTP control.
Output

How tool calling works under the hood

The rest of this page builds that loop by hand with raw Responses API requests: defining tools, reading function_call items, and sending function_call_output items back to the model.

Basic Tool Definition

Define tools using the OpenAI function calling format:
Output

Tool Choice Options

Control when and how tools are called:

Force Specific Tool

Disable Tool Calling

Multiple Tools

Define multiple tools for complex workflows:
Output

Parallel Tool Calls

The API supports parallel execution of multiple tools:
Output

Tool Call Response

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

Tool Responses in Conversation

Include tool responses in follow-up requests:
Output
Optional FieldThe id field is optional for function_call_output objects. Only type, call_id, and output are required — call_id is what pairs the output with its originating function_call. The examples above include id for completeness, but you can safely omit it.

Multimodal tool outputs

function_call_output.output accepts either a string or an array of input content parts (input_text, input_image, input_file) — the same shape as user-message content. Use the array form to return images or files from a tool; the non-text parts are only forwarded to supported multimodal models.

Streaming Tool Calls

Monitor tool calls in real-time with streaming:
Output

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