> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Tools

> Use client tools in your prompts

Tool calls (also known as function calls) give an LLM access to external tools. The LLM does not call the tools directly. Instead, it suggests the tool to call. The user then calls the tool separately and provides the results back to the LLM. Finally, the LLM formats the response into an answer to the user's original question.

OpenRouter standardizes the tool calling interface across models and providers, making it easy to integrate external tools with any supported model.

**Supported Models**: You can find models that support tool calling by filtering on [openrouter.ai/models?supported\_parameters=tools](https://openrouter.ai/models?supported_parameters=tools).

If you prefer to learn from a full end-to-end example, keep reading.

## Tool calling with the Agent SDK

The OpenRouter Agent SDK (`@openrouter/agent` for TypeScript, `openrouter_agent` for Python) runs the tool-calling loop for you. You define a tool with a name, description, input schema, and an `execute` function. When the model requests the tool, the SDK validates the arguments, runs your function, sends the result back to the model, and repeats until the model gives a final answer.

You don't need to append output items, match tool call IDs, or write your own agentic loop. The example below uses the same Project Gutenberg book search tool as the rest of this page.

```typescript title="TypeScript" lines theme={null}
import { OpenRouter } from '@openrouter/sdk';
import { callModel, tool } from '@openrouter/agent';
import { z } from 'zod';

const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const searchGutenbergBooks = tool({
  name: 'searchGutenbergBooks',
  description:
    'Search for books in the Project Gutenberg library based on specified search terms',
  inputSchema: z.object({
    search_terms: z
      .array(z.string())
      .describe("List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)"),
  }),
  execute: async ({ search_terms }) => {
    const query = encodeURIComponent(search_terms.join(' '));
    const response = await fetch(`https://gutendex.com/books?search=${query}`);
    const data = (await response.json()) as {
      results: { id: number; title: string; authors: { name: string }[] }[];
    };
    return data.results.map((book) => ({
      id: book.id,
      title: book.title,
      authors: book.authors.map((author) => ({ name: author.name })),
    }));
  },
});

const result = callModel(openRouter, {
  model: 'google/gemini-3-flash-preview',
  instructions: 'You are a helpful assistant.',
  input: 'What are the titles of some James Joyce books?',
  tools: [searchGutenbergBooks] as const,
});

// The SDK runs the tool and sends the results back to the model
console.log(await result.getText());

```

```python title="Python" lines theme={null}
import asyncio
import os

import httpx
from pydantic import BaseModel, Field
from openrouter_agent import OpenRouter, call_model, tool


class SearchInput(BaseModel):
    search_terms: list[str] = Field(
        description="List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)"
    )


class Author(BaseModel):
    name: str


class Book(BaseModel):
    id: int
    title: str
    authors: list[Author]


class SearchOutput(BaseModel):
    books: list[Book]


def search_gutenberg_books(params: SearchInput, ctx) -> SearchOutput:
    response = httpx.get(
        "https://gutendex.com/books",
        params={"search": " ".join(params.search_terms)},
        timeout=30,
    )
    data = response.json()
    return SearchOutput(
        books=[
            Book(
                id=book["id"],
                title=book["title"],
                authors=[Author(name=a["name"]) for a in book["authors"]],
            )
            for book in data["results"]
        ]
    )


async def main() -> None:
    client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

    search_tool = tool(
        name="searchGutenbergBooks",
        description="Search for books in the Project Gutenberg library based on specified search terms",
        input_schema=SearchInput,
        output_schema=SearchOutput,
        execute=search_gutenberg_books,
    )

    result = call_model(
        client,
        {
            "model": "google/gemini-3-flash-preview",
            "instructions": "You are a helpful assistant.",
            "input": "What are the titles of some James Joyce books?",
            "tools": [search_tool],
        },
    )

    # The SDK runs the tool and sends the results back to the model
    print(await result.get_text())


asyncio.run(main())

```

```text title="Output" theme={null}
Some of the most famous books and works by **James Joyce** include:

*   ***Ulysses*** (1922) – His most famous work, known for its stream-of-consciousness technique.
*   ***A Portrait of the Artist as a Young Man*** (1916) – A semi-autobiographical novel featuring his recurring character Stephen Dedalus.
*   ***Dubliners*** (1914) – A collection of 15 short stories depicting life in Dublin at the turn of the century (includes the famous story "The Dead").
*   ***Finnegans Wake*** (1939) – His final, highly experimental, and complex work.
*   ***Chamber Music*** (1907) – A collection of poetry.
*   ***Exiles*** (1918) – Joyce's only published play.
*   ***Pomes Penyeach*** (1927) – Another collection of his poetry.
*   ***Stephen Hero*** (Published posthumously in 1944) – An early draft and precursor to *A Portrait of the Artist as a Young Man*.
```

## How tool calling works under the hood

The rest of this page does by hand what the Agent SDK does for you: it sends the tools, runs the requested calls, returns the results to the model, and loops until the model gives a final answer.

### Request Body Examples

Tool calling with OpenRouter involves three key steps. Here are the essential request body formats for each step, first for the [Responses API](https://openrouter.ai/docs/api_reference/responses/overview.md) (`POST /api/v1/responses`) and then for Chat Completions (`POST /api/v1/chat/completions`).

#### Responses API

##### Step 1: Inference Request with Tools

```json expandable lines theme={null}
{
  "model": "google/gemini-3-flash-preview",
  "input": [
    {
      "role": "user",
      "content": "What are the titles of some James Joyce books?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "search_gutenberg_books",
      "description": "Search for books in the Project Gutenberg library",
      "parameters": {
        "type": "object",
        "properties": {
          "search_terms": {
            "type": "array",
            "items": {"type": "string"},
            "description": "List of search terms to find books"
          }
        },
        "required": ["search_terms"],
        "additionalProperties": false
      }
    }
  ]
}
```

##### Step 2: Tool Execution (Client-Side)

After receiving a response whose `output` contains a `function_call` item, execute the requested tool locally and prepare the result:

```javascript lines theme={null}
// Model responds with a function_call output item, you execute the tool locally
const toolResult = await searchGutenbergBooks(["James", "Joyce"]);
```

```python title="Python" lines theme={null}
# Model responds with a function_call output item, you execute the tool locally
tool_result = search_gutenberg_books(["James", "Joyce"])
```

```go title="Go" lines theme={null}
// Model responds with a function_call output item, you execute the tool locally
toolResult, err := searchGutenbergBooks([]string{"James", "Joyce"})
if err != nil {
	log.Fatal(err)
}
```

##### Step 3: Inference Request with Tool Results

```json expandable lines theme={null}
{
  "model": "google/gemini-3-flash-preview",
  "input": [
    {
      "role": "user",
      "content": "What are the titles of some James Joyce books?"
    },
    {
      "type": "function_call",
      "call_id": "call_abc123",
      "name": "search_gutenberg_books",
      "arguments": "{\"search_terms\": [\"James\", \"Joyce\"]}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_abc123",
      "output": "[{\"id\": 4300, \"title\": \"Ulysses\", \"authors\": [{\"name\": \"Joyce, James\"}]}]"
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "search_gutenberg_books",
      "description": "Search for books in the Project Gutenberg library",
      "parameters": {
        "type": "object",
        "properties": {
          "search_terms": {
            "type": "array",
            "items": {"type": "string"},
            "description": "List of search terms to find books"
          }
        },
        "required": ["search_terms"],
        "additionalProperties": false
      }
    }
  ]
}
```

#### Chat Completions API

On Chat Completions, function tools are nested under `function`, the model returns `tool_calls` on an assistant message, and tool results go back as `role: "tool"` messages.

##### Step 1: Inference Request with Tools

```json expandable lines theme={null}
{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role": "user",
      "content": "What are the titles of some James Joyce books?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_gutenberg_books",
        "description": "Search for books in the Project Gutenberg library",
        "parameters": {
          "type": "object",
          "properties": {
            "search_terms": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of search terms to find books"
            }
          },
          "required": ["search_terms"]
        }
      }
    }
  ]
}
```

##### Step 2: Tool Execution (Client-Side)

After receiving the model's response with `tool_calls`, execute the requested tool locally and prepare the result:

```javascript lines theme={null}
// Model responds with tool_calls, you execute the tool locally
const toolResult = await searchGutenbergBooks(["James", "Joyce"]);
```

```bash title="cURL" lines theme={null}
# Model responds with tool_calls, you execute the tool locally
TOOL_RESULT=$(search_gutenberg_books "James" "Joyce")
```

##### Step 3: Inference Request with Tool Results

```json expandable lines theme={null}
{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role": "user",
      "content": "What are the titles of some James Joyce books?"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "search_gutenberg_books",
            "arguments": "{\"search_terms\": [\"James\", \"Joyce\"]}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "[{\"id\": 4300, \"title\": \"Ulysses\", \"authors\": [{\"name\": \"Joyce, James\"}]}]"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_gutenberg_books",
        "description": "Search for books in the Project Gutenberg library",
        "parameters": {
          "type": "object",
          "properties": {
            "search_terms": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of search terms to find books"
            }
          },
          "required": ["search_terms"]
        }
      }
    }
  ]
}
```

**Note**: On both APIs, the `tools` parameter must be included in every request (Steps 1 and 3) so the router can validate the tool schema on each call.

#### Tool Calling Example

Here is an end-to-end example that gives LLMs the ability to call an external API -- in this case Project Gutenberg, to search for books.

First, let's do some basic setup:

```typescript title="TypeScript SDK" expandable lines theme={null}
import type {
  FunctionCallOutputItem,
  InputsUnion1,
  OpenAIResponsesRefusalContent,
  OpenResponsesResult,
  OutputFunctionCallItem,
  OutputMessageItem,
  OutputReasoningItem,
  ResponseOutputText,
  ResponsesRequestToolFunction,
} from '@openrouter/sdk/models';
import { OpenRouter } from '@openrouter/sdk';

const OPENROUTER_API_KEY = "<OPENROUTER_API_KEY>";

// You can use any model that supports tool calling
const MODEL = "google/gemini-3-flash-preview";

const openRouter = new OpenRouter({
  apiKey: OPENROUTER_API_KEY,
});

const instructions = "You are a helpful assistant.";
const task = "What are the titles of some James Joyce books?";

const input: InputsUnion1[] = [
  {
    role: "user",
    content: task,
  }
];

function convertOutputItemToInput(
  item: OpenResponsesResult['output'][number],
): InputsUnion1 {
  if (isOutputMessageItem(item)) {
    const content = item.content.filter(isKnownMessageContent);
    if (content.length !== item.content.length) {
      throw new Error('Received an unsupported message content type');
    }
    return { ...item, content };
  }

  if (isFunctionCallOrReasoningItem(item)) {
    return item;
  }

  throw new Error(`Received an unexpected output item: ${item.type}`);
}

function isOutputMessageItem(
  item: OpenResponsesResult['output'][number],
): item is OutputMessageItem {
  return item.type === 'message';
}

function isKnownMessageContent(
  content: OutputMessageItem['content'][number],
): content is OpenAIResponsesRefusalContent | ResponseOutputText {
  return content.type === 'output_text' || content.type === 'refusal';
}

function isFunctionCallOrReasoningItem(
  item: OpenResponsesResult['output'][number],
): item is OutputFunctionCallItem | OutputReasoningItem {
  return item.type === 'function_call' || item.type === 'reasoning';
}
```

```python Python expandable lines theme={null}
import json, requests
from openai import OpenAI

OPENROUTER_API_KEY = f"<OPENROUTER_API_KEY>"

# You can use any model that supports tool calling
MODEL = "google/gemini-3-flash-preview"

openai_client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key=OPENROUTER_API_KEY,
)

instructions = "You are a helpful assistant."
task = "What are the titles of some James Joyce books?"

input_items = [
  {
    "role": "user",
    "content": task,
  }
]

```

```typescript title="TypeScript (fetch)" lines theme={null}
const instructions = 'You are a helpful assistant.';

const input: unknown[] = [
  {
    role: 'user',
    content: 'What are the titles of some James Joyce books?',
  },
];
```

```go title="Go" lines theme={null}
// You can use any model that supports tool calling
const MODEL = "google/gemini-3-flash-preview"

const instructions = "You are a helpful assistant."

var input = []any{
	map[string]any{
		"role":    "user",
		"content": "What are the titles of some James Joyce books?",
	},
}
```

```bash title="cURL" lines theme={null}
# You can use any model that supports tool calling
MODEL="google/gemini-3-flash-preview"
INSTRUCTIONS="You are a helpful assistant."
INPUT='[{"role": "user", "content": "What are the titles of some James Joyce books?"}]'
```

#### Define the Tool

Next, we define the tool that we want to call. Remember, the tool is going to get *requested* by the LLM, but the code we are writing here is ultimately responsible for executing the call and returning the results to the LLM.

```typescript title="TypeScript SDK" expandable lines theme={null}
type Book = {
  id: number;
  title: string;
  authors: { name: string }[];
};

async function searchGutenbergBooks(searchTerms: string[]): Promise<Book[]> {
  const searchQuery = searchTerms.join(' ');
  const url = 'https://gutendex.com/books';
  const response = await fetch(`${url}?search=${searchQuery}`);
  const data: unknown = await response.json();

  if (!isGutenbergResponse(data)) {
    throw new Error('Invalid response from the Gutenberg API');
  }

  return data.results.map((book) => ({
    id: book.id,
    title: book.title,
    authors: book.authors.map((author) => ({ name: author.name })),
  }));
}

const tools: ResponsesRequestToolFunction[] = [
  {
    type: 'function',
    name: 'searchGutenbergBooks',
    description:
      'Search for books in the Project Gutenberg library based on specified search terms',
    parameters: {
      type: 'object',
      properties: {
        search_terms: {
          type: 'array',
          items: {
            type: 'string',
          },
          description:
            "List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)",
        },
      },
      required: ['search_terms'],
    },
  },
];

function parseSearchTerms(argumentsJson: string): string[] {
  const args: unknown = JSON.parse(argumentsJson);

  if (
    !isRecord(args) ||
    !isStringArray(args.search_terms)
  ) {
    throw new Error('Invalid arguments for searchGutenbergBooks');
  }

  return args.search_terms;
}

function isGutenbergResponse(value: unknown): value is { results: Book[] } {
  return isRecord(value) && Array.isArray(value.results) && value.results.every(isBook);
}

function isBook(value: unknown): value is Book {
  return (
    isRecord(value) &&
    typeof value.id === 'number' &&
    typeof value.title === 'string' &&
    Array.isArray(value.authors) &&
    value.authors.every(isBookAuthor)
  );
}

function isBookAuthor(value: unknown): value is { name: string } {
  return isRecord(value) && typeof value.name === 'string';
}

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((item: unknown) => typeof item === 'string');
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null;
}
```

```python Python expandable lines theme={null}
def search_gutenberg_books(search_terms):
    search_query = " ".join(search_terms)
    url = "https://gutendex.com/books"
    response = requests.get(url, params={"search": search_query})

    simplified_results = []
    for book in response.json().get("results", []):
        simplified_results.append({
            "id": book.get("id"),
            "title": book.get("title"),
            "authors": book.get("authors")
        })

    return simplified_results

tools = [
  {
    "type": "function",
    "name": "search_gutenberg_books",
    "description": "Search for books in the Project Gutenberg library based on specified search terms",
    "parameters": {
      "type": "object",
      "properties": {
        "search_terms": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)"
        }
      },
      "required": ["search_terms"]
    }
  }
]

TOOL_MAPPING = {
    "search_gutenberg_books": search_gutenberg_books
}

```

```typescript title="TypeScript (fetch)" expandable lines theme={null}
type Book = { id: number; title: string; authors: { name: string }[] };

async function searchGutenbergBooks(searchTerms: string[]): Promise<Book[]> {
  const query = encodeURIComponent(searchTerms.join(' '));
  const response = await fetch(`https://gutendex.com/books?search=${query}`);
  const data = await response.json();
  return data.results.map((book: Book) => ({
    id: book.id,
    title: book.title,
    authors: book.authors,
  }));
}

const tools = [
  {
    type: 'function',
    name: 'search_gutenberg_books',
    description:
      'Search for books in the Project Gutenberg library based on specified search terms',
    parameters: {
      type: 'object',
      properties: {
        search_terms: {
          type: 'array',
          items: { type: 'string' },
          description:
            "List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)",
        },
      },
      required: ['search_terms'],
    },
  },
];
```

```go title="Go" lines theme={null}
type Book struct {
	ID      int    `json:"id"`
	Title   string `json:"title"`
	Authors []struct {
		Name string `json:"name"`
	} `json:"authors"`
}

func searchGutenbergBooks(searchTerms []string) ([]Book, error) {
	query := url.QueryEscape(strings.Join(searchTerms, " "))
	resp, err := http.Get("https://gutendex.com/books?search=" + query)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("Gutenberg search failed: %s", resp.Status)
	}
	var data struct {
		Results []Book `json:"results"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return nil, err
	}
	return data.Results, nil
}

// runSearch decodes a function call's arguments and runs the search. Invalid arguments
// and failed lookups go back to the model as an error, never as an empty result.
func runSearch(arguments string) string {
	var args struct {
		SearchTerms []string `json:"search_terms"`
	}
	var result any
	if err := json.Unmarshal([]byte(arguments), &args); err != nil {
		result = map[string]string{"error": "invalid arguments: " + err.Error()}
	} else if books, err := searchGutenbergBooks(args.SearchTerms); err != nil {
		result = map[string]string{"error": err.Error()}
	} else {
		result = books
	}
	out, _ := json.Marshal(result)
	return string(out)
}

var tools = []map[string]any{
	{
		"type":        "function",
		"name":        "search_gutenberg_books",
		"description": "Search for books in the Project Gutenberg library based on specified search terms",
		"parameters": map[string]any{
			"type": "object",
			"properties": map[string]any{
				"search_terms": map[string]any{
					"type":        "array",
					"items":       map[string]any{"type": "string"},
					"description": "List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)",
				},
			},
			"required": []string{"search_terms"},
		},
	},
}
```

```bash title="cURL" lines theme={null}
search_gutenberg_books() {
  local query body
  query=$(jq -rn --arg q "$*" '$q | @uri')
  body=$(curl -sfL "https://gutendex.com/books?search=$query") || return 1
  jq '[.results[] | {id, title, authors}]' <<<"$body"
}

TOOLS=$(cat <<'EOF'
[
  {
    "type": "function",
    "name": "search_gutenberg_books",
    "description": "Search for books in the Project Gutenberg library based on specified search terms",
    "parameters": {
      "type": "object",
      "properties": {
        "search_terms": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of search terms to find books in the Gutenberg library (e.g. ['dickens', 'great'] to search for books by Dickens with 'great' in the title)"
        }
      },
      "required": ["search_terms"]
    }
  }
]
EOF
)
```

Note that the "tool" is just a normal function. We then write a JSON "spec" compatible with the OpenAI function calling parameter. We'll pass that spec to the LLM so that it knows this tool is available and how to use it. It will request the tool when needed, along with any arguments. We'll then marshal the tool call locally, make the function call, and return the results to the LLM.

#### Tool use and tool results

Let's make the first OpenRouter API call to the model:

```typescript title="TypeScript SDK" lines theme={null}
const response_1 = await openRouter.responses.send({
  responsesRequest: {
    model: MODEL,
    instructions,
    tools,
    input,
    stream: false,
  },
});

if (!('output' in response_1)) {
  throw new Error('Expected a non-streaming response');
}
```

```python Python lines theme={null}
request_1 = {
    "model": MODEL,
    "instructions": instructions,
    "tools": tools,
    "input": input_items
}

response_1 = openai_client.responses.create(**request_1)
```

```typescript title="TypeScript (fetch)" lines theme={null}
const request_1 = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer <OPENROUTER_API_KEY>`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: MODEL,
    instructions,
    tools,
    input,
  }),
});

const data_1 = await request_1.json();
```

```go title="Go" lines theme={null}
body, _ := json.Marshal(map[string]any{
	"model":        MODEL,
	"instructions": instructions,
	"tools":        tools,
	"input":        input,
	"stream":       false,
})
req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()

var response1 map[string]any
json.NewDecoder(resp.Body).Decode(&response1)
if _, ok := response1["output"]; !ok {
	log.Fatalf("Expected a non-streaming response: %v", response1)
}
```

```bash title="cURL" lines theme={null}
RESPONSE_1=$(curl -s https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg model "$MODEL" \
    --arg instructions "$INSTRUCTIONS" \
    --argjson tools "$TOOLS" \
    --argjson input "$INPUT" \
    '{model: $model, instructions: $instructions, tools: $tools, input: $input, stream: false}')")

echo "$RESPONSE_1" | jq -e 'has("output")' > /dev/null \
  || { echo "Expected a non-streaming response" >&2; exit 1; }
```

`response.output` contains `function_call` items with a `call_id`, `name`, and JSON-encoded `arguments`. Production code should verify that at least one exists; this example assumes one does:

```typescript title="TypeScript SDK" lines theme={null}
const toolCalls = response_1.output.filter(
  (item): item is OutputFunctionCallItem => item.type === 'function_call',
);

if (toolCalls.length === 0) {
  throw new Error('Expected the model to request a tool call');
}

// Append every output item in order so the LLM has the full context.
// It's easy to forget this step!
input.push(...response_1.output.map(convertOutputItemToInput));

// Now we process the requested tool calls, and use our book lookup tool
for (const toolCall of toolCalls) {
  if (toolCall.name !== 'searchGutenbergBooks') {
    throw new Error(`Unknown tool: ${toolCall.name}`);
  }

  const searchTerms = parseSearchTerms(toolCall.arguments);
  const toolResponse = await searchGutenbergBooks(searchTerms);
  input.push({
    type: 'function_call_output',
    callId: toolCall.callId,
    output: JSON.stringify(toolResponse),
  });
}
```

```python Python lines theme={null}
# Append the model's output items to the input array so the LLM has the full context
# It's easy to forget this step!
input_items += response_1.output

# Now we process the requested tool calls, and use our book lookup tool
for item in response_1.output:
    if item.type != "function_call":
        continue
    '''
    In this case we only provided one tool, so we know what function to call.
    When providing multiple tools, you can inspect `item.name`
    to figure out what function you need to call locally.
    '''
    tool_name = item.name
    tool_args = json.loads(item.arguments)
    tool_response = TOOL_MAPPING[tool_name](**tool_args)
    input_items.append({
      "type": "function_call_output",
      "call_id": item.call_id,
      "output": json.dumps(tool_response),
    })
```

```typescript title="TypeScript (fetch)" lines theme={null}
const toolCalls = data_1.output.filter(
  (item: { type: string }) => item.type === 'function_call',
);

// Carry every output item forward in order so the model has the full context
// It's easy to forget this step!
const input_2 = [
  ...input,
  ...data_1.output,
];

// Now we process the requested tool calls, and use our book lookup tool
for (const toolCall of toolCalls) {
  if (toolCall.name !== 'search_gutenberg_books') {
    throw new Error(`Unknown tool: ${toolCall.name}`);
  }

  const { search_terms } = JSON.parse(toolCall.arguments);
  const toolResponse = await searchGutenbergBooks(search_terms);
  input_2.push({
    type: 'function_call_output',
    call_id: toolCall.call_id,
    output: JSON.stringify(toolResponse),
  });
}
```

```go title="Go" lines theme={null}
// Append the model's output items to the input array so the LLM has the full context
// It's easy to forget this step!
output := response1["output"].([]any)
input = append(input, output...)

// Now we process the requested tool calls, and use our book lookup tool
for _, o := range output {
	item := o.(map[string]any)
	if item["type"] != "function_call" {
		continue
	}
	// In this case we only provided one tool, so we know what function to call.
	// When providing multiple tools, you can inspect item["name"]
	// to figure out what function you need to call locally.
	input = append(input, map[string]any{
		"type":    "function_call_output",
		"call_id": item["call_id"],
		"output":  runSearch(item["arguments"].(string)),
	})
}
```

```bash title="cURL" lines theme={null}
# Append the model's output items to the input array so the LLM has the full context
# It's easy to forget this step!
INPUT=$(jq -c --argjson output "$(jq -c '.output' <<<"$RESPONSE_1")" '. + $output' <<<"$INPUT")

# Now we process the requested tool calls, and use our book lookup tool
while IFS= read -r call; do
  terms=$(jq -er '.arguments | fromjson | .search_terms | join(" ")' <<<"$call") \
    || { echo "Invalid arguments for search_gutenberg_books" >&2; exit 1; }
  result=$(search_gutenberg_books "$terms") \
    || { echo "Gutenberg search failed" >&2; exit 1; }
  INPUT=$(jq -c --arg call_id "$(jq -r '.call_id' <<<"$call")" --arg output "$result" \
    '. + [{type: "function_call_output", call_id: $call_id, output: $output}]' <<<"$INPUT")
done < <(jq -c '.output[] | select(.type == "function_call")' <<<"$RESPONSE_1")
```

The input array now has:

1. Our original request
2. The LLM's reasoning items, when present, and `function_call` items
3. A `function_call_output` item with the tool result

Now, we can make a second OpenRouter API call, and hopefully get our result!

```typescript title="TypeScript SDK" lines theme={null}
const response_2 = await openRouter.responses.send({
  responsesRequest: {
    model: MODEL,
    instructions,
    input,
    tools,
    stream: false,
  },
});

if (!('output' in response_2)) {
  throw new Error('Expected a non-streaming response');
}

const finalMessage = [...response_2.output].reverse().find((item) => item.type === 'message');
console.log(finalMessage?.content.find((part) => part.type === 'output_text')?.text);
```

```python Python lines theme={null}
request_2 = {
  "model": MODEL,
  "instructions": instructions,
  "input": input_items,
  "tools": tools
}

response_2 = openai_client.responses.create(**request_2)

print(response_2.output_text)
```

```typescript title="TypeScript (fetch)" lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer <OPENROUTER_API_KEY>`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: MODEL,
    instructions,
    input: input_2,
    tools,
  }),
});

const data = await response.json();
const message = [...data.output].reverse().find((item: { type: string }) => item.type === 'message');
console.log(message?.content.find((part: { type: string; text?: string }) => part.type === 'output_text')?.text);
```

```go title="Go" lines theme={null}
body2, _ := json.Marshal(map[string]any{
	"model":        MODEL,
	"instructions": instructions,
	"input":        input,
	"tools":        tools,
	"stream":       false,
})
req2, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body2))
req2.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
req2.Header.Set("Content-Type", "application/json")
resp2, err := http.DefaultClient.Do(req2)
if err != nil {
	log.Fatal(err)
}
defer resp2.Body.Close()

var response2 map[string]any
json.NewDecoder(resp2.Body).Decode(&response2)
output2, ok := response2["output"].([]any)
if !ok {
	log.Fatalf("Expected a non-streaming response: %v", response2)
}

// Print the text of the last message item
for i := len(output2) - 1; i >= 0; i-- {
	item := output2[i].(map[string]any)
	if item["type"] != "message" {
		continue
	}
	for _, p := range item["content"].([]any) {
		if part := p.(map[string]any); part["type"] == "output_text" {
			fmt.Println(part["text"])
			break
		}
	}
	break
}
```

```bash title="cURL" lines theme={null}
RESPONSE_2=$(curl -s https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg model "$MODEL" \
    --arg instructions "$INSTRUCTIONS" \
    --argjson input "$INPUT" \
    --argjson tools "$TOOLS" \
    '{model: $model, instructions: $instructions, input: $input, tools: $tools, stream: false}')")

echo "$RESPONSE_2" | jq -e 'has("output")' > /dev/null \
  || { echo "Expected a non-streaming response" >&2; exit 1; }

echo "$RESPONSE_2" | jq -r '[.output[] | select(.type == "message")] | last | .content[] | select(.type == "output_text") | .text'
```

The output will be something like:

```text lines theme={null}
Here are some books by James Joyce:

*   *Ulysses*
*   *Dubliners*
*   *A Portrait of the Artist as a Young Man*
*   *Chamber Music*
*   *Exiles: A Play in Three Acts*
```

We did it! We've successfully used a tool in a prompt.

### Interleaved Thinking

Interleaved thinking allows models to reason between tool calls, enabling more sophisticated decision-making after receiving tool results. This feature helps models chain multiple tool calls with reasoning steps in between and make nuanced decisions based on intermediate results.

**Important**: Interleaved thinking increases token usage and response latency. Consider your budget and performance requirements when enabling this feature.

#### How Interleaved Thinking Works

With interleaved thinking, the model can:

* Reason about the results of a tool call before deciding what to do next
* Chain multiple tool calls with reasoning steps in between
* Make more nuanced decisions based on intermediate results
* Provide transparent reasoning for its tool selection process

#### Example: Multi-Step Research with Reasoning

Here's an example showing how a model might use interleaved thinking to research a topic across multiple sources:

**Initial Request:**

```json expandable lines theme={null}
{
  "model": "anthropic/claude-sonnet-4.5",
  "input": [
    {
      "role": "user",
      "content": "Research the environmental impact of electric vehicles and provide a comprehensive analysis."
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "search_academic_papers",
      "description": "Search for academic papers on a given topic",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "field": {"type": "string"}
        },
        "required": ["query"]
      }
    },
    {
      "type": "function",
      "name": "get_latest_statistics",
      "description": "Get latest statistics on a topic",
      "parameters": {
        "type": "object",
        "properties": {
          "topic": {"type": "string"},
          "year": {"type": "integer"}
        },
        "required": ["topic"]
      }
    }
  ]
}
```

**Model's Reasoning and Tool Calls:**

1. **Initial Thinking**: "I need to research electric vehicle environmental impact. Let me start with academic papers to get peer-reviewed research."

2. **First Tool Call**: `search_academic_papers({"query": "electric vehicle lifecycle environmental impact", "field": "environmental science"})`

3. **After First Tool Result**: "The papers show mixed results on manufacturing impact. I need current statistics to complement this academic research."

4. **Second Tool Call**: `get_latest_statistics({"topic": "electric vehicle carbon footprint", "year": 2024})`

5. **After Second Tool Result**: "Now I have both academic research and current data. Let me search for manufacturing-specific studies to address the gaps I found."

6. **Third Tool Call**: `search_academic_papers({"query": "electric vehicle battery manufacturing environmental cost", "field": "materials science"})`

7. **Final Analysis**: Synthesizes all gathered information into a comprehensive response.

#### Best Practices for Interleaved Thinking

* **Clear Tool Descriptions**: Provide detailed descriptions so the model can reason about when to use each tool
* **Structured Parameters**: Use well-defined parameter schemas to help the model make precise tool calls
* **Context Preservation**: Maintain conversation context across multiple tool interactions
* **Error Handling**: Design tools to provide meaningful error messages that help the model adjust its approach

#### Implementation Considerations

When implementing interleaved thinking:

* Models may take longer to respond due to additional reasoning steps
* Token usage will be higher due to the reasoning process
* The quality of reasoning depends on the model's capabilities
* Some models may be better suited for this approach than others

### A Simple Agentic Loop

In the example above, the calls are made explicitly and sequentially. To handle a wide variety of user inputs and tool calls, you can use an agentic loop.

Here's an example of a simple agentic loop (using the same `tools`, `instructions`, and initial `input` as above):

```typescript title="TypeScript SDK" expandable lines theme={null}
async function callLLM(input: InputsUnion1[]): Promise<OpenResponsesResult> {
  const result = await openRouter.responses.send({
    responsesRequest: {
      model: MODEL,
      instructions,
      tools,
      input,
      stream: false,
    },
  });

  if (!('output' in result)) {
    throw new Error('Expected a non-streaming response');
  }
  if (result.status !== 'completed') {
    throw new Error(result.error?.message ?? `Response ended as ${result.status}`);
  }

  // Replay every output item in order so the model keeps its full context
  input.push(...result.output.map(convertOutputItemToInput));
  return result;
}

async function getToolResponse(toolCall: OutputFunctionCallItem): Promise<FunctionCallOutputItem> {
  if (toolCall.name !== 'searchGutenbergBooks') {
    throw new Error(`Unknown tool: ${toolCall.name}`);
  }

  const searchTerms = parseSearchTerms(toolCall.arguments);
  const toolResult = await searchGutenbergBooks(searchTerms);

  return {
    type: 'function_call_output',
    callId: toolCall.callId,
    output: JSON.stringify(toolResult),
  };
}

const maxIterations = 10;
let iterationCount = 0;
let finalText: string | undefined;

while (iterationCount < maxIterations) {
  iterationCount++;
  const response = await callLLM(input);
  const toolCalls = response.output.filter(
    (item): item is OutputFunctionCallItem => item.type === 'function_call',
  );

  if (toolCalls.length === 0) {
    const message = [...response.output].reverse().find((item) => item.type === 'message');
    finalText = message?.content.find((part) => part.type === 'output_text')?.text ?? '';
    break;
  }

  for (const toolCall of toolCalls) {
    input.push(await getToolResponse(toolCall));
  }
}

if (finalText === undefined) {
  console.warn("Warning: Maximum iterations reached");
}

console.log(finalText);
```

```python Python expandable lines theme={null}
def call_llm(items):
    resp = openai_client.responses.create(
        model=MODEL,
        instructions=instructions,
        tools=tools,
        input=items
    )
    if resp.status != "completed":
        message = resp.error.message if resp.error else f"Response ended as {resp.status}"
        raise RuntimeError(message)
    items += resp.output
    return resp

def get_tool_response(tool_call):
    tool_name = tool_call.name
    tool_args = json.loads(tool_call.arguments)

    # Look up the correct tool locally, and call it with the provided arguments
    # Other tools can be added without changing the agentic loop
    tool_result = TOOL_MAPPING[tool_name](**tool_args)

    return {
        "type": "function_call_output",
        "call_id": tool_call.call_id,
        "output": json.dumps(tool_result),
    }

max_iterations = 10
iteration_count = 0
final_text = None

while iteration_count < max_iterations:
    iteration_count += 1
    resp = call_llm(input_items)

    tool_calls = [item for item in resp.output if item.type == "function_call"]
    if not tool_calls:
        final_text = resp.output_text
        break

    for tool_call in tool_calls:
        input_items.append(get_tool_response(tool_call))

if final_text is None:
    print("Warning: Maximum iterations reached")

print(final_text)
```

```go title="Go" lines theme={null}
callLLM := func() []any {
	body, _ := json.Marshal(map[string]any{
		"model":        MODEL,
		"instructions": instructions,
		"tools":        tools,
		"input":        input,
		"stream":       false,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	output, ok := result["output"].([]any)
	if !ok {
		log.Fatalf("Expected a non-streaming response: %v", result)
	}
	if result["status"] != "completed" {
		log.Fatalf("Response ended as %v: %v", result["status"], result["error"])
	}

	// Replay every output item in order so the model keeps its full context
	input = append(input, output...)
	return output
}

getToolResponse := func(toolCall map[string]any) map[string]any {
	if toolCall["name"] != "search_gutenberg_books" {
		log.Fatalf("Unknown tool: %v", toolCall["name"])
	}

	return map[string]any{
		"type":    "function_call_output",
		"call_id": toolCall["call_id"],
		"output":  runSearch(toolCall["arguments"].(string)),
	}
}

maxIterations := 10
finalText, done := "", false

for iterationCount := 0; iterationCount < maxIterations; iterationCount++ {
	output := callLLM()
	var toolCalls []map[string]any
	for _, o := range output {
		if item := o.(map[string]any); item["type"] == "function_call" {
			toolCalls = append(toolCalls, item)
		}
	}

	if len(toolCalls) == 0 {
		for i := len(output) - 1; i >= 0 && !done; i-- {
			item := output[i].(map[string]any)
			if item["type"] != "message" {
				continue
			}
			for _, p := range item["content"].([]any) {
				if part := p.(map[string]any); part["type"] == "output_text" {
					finalText, _ = part["text"].(string)
					break
				}
			}
			done = true
		}
		done = true
		break
	}

	for _, toolCall := range toolCalls {
		input = append(input, getToolResponse(toolCall))
	}
}

if !done {
	log.Println("Warning: Maximum iterations reached")
}

fmt.Println(finalText)
```

### Best Practices and Advanced Patterns

#### Function Definition Guidelines

When defining tools for LLMs, follow these best practices:

**Clear and Descriptive Names**: Use descriptive function names that clearly indicate the tool's purpose.

```json lines theme={null}
// Good: Clear and specific
{ "name": "get_weather_forecast" }
```

```json lines theme={null}
// Avoid: Too vague
{ "name": "weather" }
```

**Comprehensive Descriptions**: Provide detailed descriptions that help the model understand when and how to use the tool.

```json lines theme={null}
{
  "description": "Get current weather conditions and 5-day forecast for a specific location. Supports cities, zip codes, and coordinates.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name, zip code, or coordinates (lat,lng). Examples: 'New York', '10001', '40.7128,-74.0060'"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit preference",
        "default": "celsius"
      }
    },
    "required": ["location"]
  }
}
```

#### Streaming with Tool Calls

When using streaming responses with tool calls, handle the different content types appropriately. The Python, Go, and cURL tabs define the tool-call handler they use; `handleToolCalls` in the TypeScript tab is your own function with the same job:

```typescript expandable lines theme={null}
const stream = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4.5',
    input: input,
    tools: tools,
    stream: true
  })
});

if (!stream.body) {
  throw new Error('Expected a streaming response body');
}

const reader = stream.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
const toolCalls = [];
const outputItems = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) {
    break;
  }

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() ?? '';

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    const data = line.slice(6).trim();
    if (data === '[DONE]') continue;

    const event = JSON.parse(data);

    if (event.type === 'response.failed') {
      throw new Error(event.response.error?.message ?? 'Response failed');
    }
    if (event.type === 'response.incomplete') {
      throw new Error(
        `Response incomplete: ${event.response.incomplete_details?.reason ?? 'unknown reason'}`,
      );
    }
    if (event.type === 'response.output_text.delta') {
      console.log(event.delta);
    }

    if (event.type === 'response.output_item.done') {
      // Preserve every completed item in order. Reasoning and assistant items are
      // required context for some providers when sending tool results.
      outputItems.push(event.item);
      if (event.item.type === 'function_call') {
        // A completed function_call item carries the full arguments string.
        toolCalls.push(event.item);
      }
    }

    if (event.type === 'response.completed') {
      if (toolCalls.length > 0) {
        // Run each function_call locally, then send a follow-up request whose input
        // includes the original input, every output item, and a function_call_output
        // for each call (see the non-streaming loop above).
        await handleToolCalls(toolCalls, outputItems);
      }
      // Otherwise the regular response was printed from its output_text deltas above
    }
  }
}
```

```python title="Python" expandable lines theme={null}
HEADERS = {
    "Authorization": f"Bearer {OPENROUTER_API_KEY}",
    "Content-Type": "application/json",
}


# Runs each function_call, then sends one non-streaming follow-up request with the results
def handle_tool_calls(tool_calls, output_items):
    results = []
    for call in tool_calls:
        tool_result = TOOL_MAPPING[call["name"]](**json.loads(call["arguments"]))
        results.append({
            "type": "function_call_output",
            "call_id": call["call_id"],
            "output": json.dumps(tool_result),
        })

    follow_up = requests.post(
        "https://openrouter.ai/api/v1/responses",
        headers=HEADERS,
        json={
            "model": "anthropic/claude-sonnet-4.5",
            "input": input_items + output_items + results,
            "tools": tools,
        },
    )
    follow_up.raise_for_status()
    for item in follow_up.json()["output"]:
        if item["type"] != "message":
            continue
        for part in item["content"]:
            if part["type"] == "output_text":
                print(part["text"])


response = requests.post(
    "https://openrouter.ai/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "anthropic/claude-sonnet-4.5",
        "input": input_items,
        "tools": tools,
        "stream": True,
    },
    stream=True,
)
response.raise_for_status()

tool_calls = []
output_items = []

for raw_line in response.iter_lines():
    line = raw_line.decode("utf-8")
    if not line.startswith("data: "):
        continue
    data = line[6:].strip()
    if data == "[DONE]":
        continue

    event = json.loads(data)

    if event["type"] == "response.failed":
        error = event["response"].get("error") or {}
        raise RuntimeError(error.get("message", "Response failed"))
    if event["type"] == "response.incomplete":
        details = event["response"].get("incomplete_details") or {}
        raise RuntimeError(f"Response incomplete: {details.get('reason', 'unknown reason')}")
    if event["type"] == "response.output_text.delta":
        print(event["delta"], end="", flush=True)

    if event["type"] == "response.output_item.done":
        # Preserve every completed item in order. Reasoning and assistant items are
        # required context for some providers when sending tool results.
        output_items.append(event["item"])
        if event["item"]["type"] == "function_call":
            # A completed function_call item carries the full arguments string.
            tool_calls.append(event["item"])

    if event["type"] == "response.completed":
        print()
        if tool_calls:
            # Run each function_call locally, then send a follow-up request whose input
            # includes the original input, every output item, and a function_call_output
            # for each call (see the non-streaming loop above).
            handle_tool_calls(tool_calls, output_items)
        # Otherwise the regular response was printed from its output_text deltas above

```

```go title="Go" expandable lines theme={null}
// Runs each function_call, then sends one non-streaming follow-up request with the results
handleToolCalls := func(toolCalls []map[string]any, outputItems []any) {
	followUp := append(append([]any{}, input...), outputItems...)
	for _, call := range toolCalls {
		followUp = append(followUp, map[string]any{
			"type":    "function_call_output",
			"call_id": call["call_id"],
			"output":  runSearch(call["arguments"].(string)),
		})
	}

	body, _ := json.Marshal(map[string]any{
		"model": "anthropic/claude-sonnet-4.5",
		"input": followUp,
		"tools": tools,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var result struct {
		Output []struct {
			Content []struct {
				Type string `json:"type"`
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	for _, item := range result.Output {
		for _, part := range item.Content {
			if part.Type == "output_text" {
				fmt.Println(part.Text)
			}
		}
	}
}

body, _ := json.Marshal(map[string]any{
	"model":  "anthropic/claude-sonnet-4.5",
	"input":  input,
	"tools":  tools,
	"stream": true,
})
req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
stream, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer stream.Body.Close()
if stream.StatusCode != http.StatusOK {
	log.Fatalf("Expected a streaming response, got %s", stream.Status)
}

var toolCalls []map[string]any
var outputItems []any

scanner := bufio.NewScanner(stream.Body)
scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
for scanner.Scan() {
	line := scanner.Text()
	if !strings.HasPrefix(line, "data: ") {
		continue
	}
	data := strings.TrimSpace(line[6:])
	if data == "[DONE]" {
		continue
	}

	var event map[string]any
	if err := json.Unmarshal([]byte(data), &event); err != nil {
		log.Fatal(err)
	}

	switch event["type"] {
	case "response.failed":
		log.Fatalf("Response failed: %v", event["response"].(map[string]any)["error"])
	case "response.incomplete":
		log.Fatalf("Response incomplete: %v", event["response"].(map[string]any)["incomplete_details"])
	case "response.output_text.delta":
		fmt.Print(event["delta"])
	case "response.output_item.done":
		// Preserve every completed item in order. Reasoning and assistant items are
		// required context for some providers when sending tool results.
		item := event["item"].(map[string]any)
		outputItems = append(outputItems, item)
		if item["type"] == "function_call" {
			// A completed function_call item carries the full arguments string.
			toolCalls = append(toolCalls, item)
		}
	case "response.completed":
		fmt.Println()
		if len(toolCalls) > 0 {
			// Run each function_call locally, then send a follow-up request whose input
			// includes the original input, every output item, and a function_call_output
			// for each call (see the non-streaming loop above).
			handleToolCalls(toolCalls, outputItems)
		}
		// Otherwise the regular response was printed from its output_text deltas above
	}
}
if err := scanner.Err(); err != nil {
	log.Fatal(err)
}
```

```bash title="cURL" expandable lines theme={null}
# Runs each function_call, then sends one non-streaming follow-up request with the results
handle_tool_calls() {
  local tool_calls=$1 output_items=$2 follow_up call terms result
  follow_up=$(jq -c --argjson items "$output_items" '. + $items' <<<"$INPUT")
  while IFS= read -r call; do
    terms=$(jq -er '.arguments | fromjson | .search_terms | join(" ")' <<<"$call") || return 1
    result=$(search_gutenberg_books "$terms") || return 1
    follow_up=$(jq -c --arg call_id "$(jq -r '.call_id' <<<"$call")" --arg output "$result" \
      '. + [{type: "function_call_output", call_id: $call_id, output: $output}]' <<<"$follow_up")
  done < <(jq -c '.[]' <<<"$tool_calls")

  curl -sS https://openrouter.ai/api/v1/responses \
    -H "Authorization: Bearer $OPENROUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --argjson input "$follow_up" --argjson tools "$TOOLS" \
      '{model: "anthropic/claude-sonnet-4.5", input: $input, tools: $tools}')" |
    jq -r '.output[] | select(.type == "message") | .content[] | select(.type == "output_text") | .text'
}

output_items='[]'

curl -sSN https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --argjson input "$INPUT" --argjson tools "$TOOLS" \
    '{model: "anthropic/claude-sonnet-4.5", input: $input, tools: $tools, stream: true}')" |
while IFS= read -r line; do
  line=${line%$'\r'}
  [[ $line == "data: "* ]] || continue
  data=${line#data: }
  [[ $data == "[DONE]" ]] && continue

  case $(jq -r '.type' <<<"$data") in
    response.failed)
      jq -r '.response.error.message // "Response failed"' <<<"$data" >&2; exit 1 ;;
    response.incomplete)
      jq -r '"Response incomplete: " + (.response.incomplete_details.reason // "unknown reason")' <<<"$data" >&2; exit 1 ;;
    response.output_text.delta)
      jq -rj '.delta' <<<"$data" ;;
    response.output_item.done)
      # Preserve every completed item in order. Reasoning and assistant items are
      # required context for some providers when sending tool results.
      output_items=$(jq -c --argjson item "$(jq -c '.item' <<<"$data")" '. + [$item]' <<<"$output_items") ;;
    response.completed)
      echo
      # A completed function_call item carries the full arguments string.
      tool_calls=$(jq -c 'map(select(.type == "function_call"))' <<<"$output_items")
      if [[ $tool_calls != "[]" ]]; then
        # Run each function_call locally, then send a follow-up request whose input
        # includes the original input, every output item, and a function_call_output
        # for each call (see the non-streaming loop above).
        handle_tool_calls "$tool_calls" "$output_items"
      fi
      # Otherwise the regular response was printed from its output_text deltas above
      ;;
  esac
done
```

#### Tool Choice Configuration

Control tool usage with the `tool_choice` parameter:

```json lines theme={null}
// Let model decide (default)
{ "tool_choice": "auto" }
```

```json lines theme={null}
// Disable tool usage
{ "tool_choice": "none" }
```

```json lines theme={null}
// Force specific tool (Responses API)
{
  "tool_choice": {
    "type": "function",
    "name": "search_database"
  }
}
```

```json lines theme={null}
// Force specific tool (Chat Completions: the name is nested under `function`)
{
  "tool_choice": {
    "type": "function",
    "function": { "name": "search_database" }
  }
}
```

#### Parallel Tool Calls

Control whether multiple tools can be called simultaneously with the `parallel_tool_calls` parameter (default is true for most models):

```json lines theme={null}
// Disable parallel tool calls - tools will be called sequentially
{ "parallel_tool_calls": false }
```

When `parallel_tool_calls` is `false`, the model will only request one tool call at a time instead of potentially multiple calls in parallel.

#### Multi-Tool Workflows

Design tools that work well together:

```json expandable lines theme={null}
{
  "tools": [
    {
      "type": "function",
      "name": "search_products",
      "description": "Search for products in the catalog",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Product name or search terms" }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "get_product_details",
      "description": "Get detailed information about a specific product",
      "parameters": {
        "type": "object",
        "properties": {
          "product_id": { "type": "string", "description": "Catalog product identifier" }
        },
        "required": ["product_id"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "check_inventory",
      "description": "Check current inventory levels for a product",
      "parameters": {
        "type": "object",
        "properties": {
          "product_id": { "type": "string", "description": "Catalog product identifier" }
        },
        "required": ["product_id"],
        "additionalProperties": false
      }
    }
  ]
}
```

This allows the model to naturally chain operations: search → get details → check inventory.

#### Reliability Tracking

OpenRouter tracks how reliably each provider completes tool calls and surfaces this as the **Tool Call Error Rate** on the Performance tab of every model page. The same signal drives [Auto Exacto](https://openrouter.ai/docs/guides/routing/auto-exacto.md) provider ordering on tool-calling requests. For the exact validator, JSON Schema draft, regex semantics, and per-tool-call classification, see [How Tool-Calling Success Rate Is Measured](https://openrouter.ai/docs/guides/routing/auto-exacto.md#how-tool-calling-success-rate-is-measured).

For more details on the Responses API input format and tool parameters, see the [Responses API reference](https://openrouter.ai/docs/api_reference/responses/overview.md).
