OpenAI Tool Calling

Give your OpenAI-powered applications real-time web search capabilities by integrating Parallel Search as a tool. This guide shows how to define Parallel Search as an OpenAI function and handle tool calls in your application.

Overview

OpenAI’s tool calling (formerly function calling) allows GPT models to output structured JSON indicating they want to call a function you’ve defined. Your application then executes the function and returns results to the model. By defining Parallel Search as a tool, your model can:

Search the web for current information
Access real-time news, research, and facts
Cite sources with URLs in responses

Prerequisites

Get your Parallel API key from Platform
Get your OpenAI API key from OpenAI
Install the required SDKs:

pip install openai parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"

npm install openai parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Define the Search Tool

First, define the Parallel search tool using OpenAI’s tool schema format. See Search Tool Definition for a framework-agnostic, copy-paste-ready version.

parallel_search_tool = {
    "type": "function",
    "function": {
        "name": "search_web",
        "description": "Searches the web for current and factual information, returning relevant results with titles, URLs, and content snippets.",
        "parameters": {
            "type": "object",
            "properties": {
                "objective": {
                    "type": "string",
                    "description": "A concise, self-contained search query. Must include the key entity or topic being searched for."
                },
                "search_queries": {
                    "type": "array",
                    "description": "Exactly 3 keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles. Each query must include the key entity or topic. NEVER write sentences, instructions, or use site: operators.",
                    "items": {"type": "string"},
                    "minItems": 3,
                    "maxItems": 3
                }
            },
            "required": ["objective", "search_queries"],
            "additionalProperties": False
        },
        "strict": True
    }
}

import OpenAI from "openai";

const parallelSearchTool: OpenAI.ChatCompletionTool = {
  type: "function",
  function: {
    name: "search_web",
    description:
      "Searches the web for current and factual information, returning relevant results with titles, URLs, and content snippets.",
    parameters: {
      type: "object",
      properties: {
        objective: {
          type: "string",
          description:
            "A concise, self-contained search query. Must include the key entity or topic being searched for.",
        },
        search_queries: {
          type: "array",
          description:
            "Exactly 3 keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles. Each query must include the key entity or topic. NEVER write sentences, instructions, or use site: operators.",
          items: { type: "string" },
          minItems: 3,
          maxItems: 3,
        },
      },
      required: ["objective", "search_queries"],
      additionalProperties: false,
    },
    strict: true,
  },
};

Setting strict: true (with additionalProperties: false and every field listed in required) enables OpenAI’s structured outputs for tool arguments, preventing schema-violating arguments from the model.

Implement the Search Function

Create a function that calls the Parallel Search API when the model requests it:

import os
import json
from parallel import Parallel

parallel_client = Parallel(api_key=os.environ["PARALLEL_API_KEY"])

def search_web(
    objective: str = None,
    search_queries: list = None,
) -> dict:
    """Execute a search using the Parallel Search API."""
    response = parallel_client.search(
        objective=objective,
        search_queries=search_queries,
    )

    # Format results for the LLM
    return {
        "results": [
            {"url": r.url, "title": r.title, "excerpts": r.excerpts[:3] if r.excerpts else []}
            for r in response.results
        ]
    }

import Parallel from "parallel-web";

const parallel = new Parallel({ apiKey: process.env.PARALLEL_API_KEY });

interface SearchParams {
  objective?: string;
  search_queries?: string[];
}

async function searchWeb(params: SearchParams) {
  const response = await parallel.search({
    objective: params.objective,
    search_queries: params.search_queries,
  });

  return {
    results: response.results.map((r) => ({
      url: r.url,
      title: r.title,
      excerpts: r.excerpts?.slice(0, 3) || [],
    })),
  };
}

Process Tool Calls

Handle the tool calls returned by OpenAI:

def process_tool_calls(tool_calls):
    """Process tool calls from OpenAI and return results."""
    results = []
    for tool_call in tool_calls:
        if tool_call.function.name == "search_web":
            args = json.loads(tool_call.function.arguments)
            search_result = search_web(
                objective=args.get("objective"),
                search_queries=args.get("search_queries"),
            )
            results.append({
                "tool_call_id": tool_call.id,
                "role": "tool",
                "content": json.dumps(search_result)
            })
    return results

async function processToolCalls(
  toolCalls: OpenAI.ChatCompletionMessageToolCall[]
) {
  const results: OpenAI.ChatCompletionToolMessageParam[] = [];

  for (const toolCall of toolCalls) {
    if (toolCall.function.name === "search_web") {
      const args = JSON.parse(toolCall.function.arguments) as SearchParams;
      const searchResult = await searchWeb(args);

      results.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(searchResult),
      });
    }
  }

  return results;
}

Complete Example

Here’s a complete example that ties everything together:

import os
import json
from openai import OpenAI
from parallel import Parallel

# Initialize clients
openai_client = OpenAI()
parallel_client = Parallel(api_key=os.environ["PARALLEL_API_KEY"])

# Tool definition
parallel_search_tool = {
    "type": "function",
    "function": {
        "name": "search_web",
        "description": "Searches the web for current and factual information, returning relevant results with titles, URLs, and content snippets.",
        "parameters": {
            "type": "object",
            "properties": {
                "objective": {
                    "type": "string",
                    "description": "A concise, self-contained search query. Must include the key entity or topic being searched for."
                },
                "search_queries": {
                    "type": "array",
                    "description": "Exactly 3 keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles. Each query must include the key entity or topic. NEVER write sentences, instructions, or use site: operators.",
                    "items": {"type": "string"},
                    "minItems": 3,
                    "maxItems": 3
                }
            },
            "required": ["objective", "search_queries"],
            "additionalProperties": False
        },
        "strict": True
    }
}


def search_web(objective=None, search_queries=None):
    response = parallel_client.search(
        objective=objective,
        search_queries=search_queries,
    )
    return {
        "results": [
            {"url": r.url, "title": r.title, "excerpts": r.excerpts[:3] if r.excerpts else []}
            for r in response.results
        ]
    }


def chat_with_search(user_message: str) -> str:
    messages = [
        {
            "role": "system",
            "content": "You are a helpful research assistant. Use the search_web tool to find current information. Always cite sources with URLs."
        },
        {"role": "user", "content": user_message}
    ]

    # First API call - may trigger tool use
    response = openai_client.chat.completions.create(
        model="gpt-5.5",
        messages=messages,
        tools=[parallel_search_tool],
        tool_choice="auto"
    )

    assistant_message = response.choices[0].message

    # Check if the model wants to use tools
    if assistant_message.tool_calls:
        messages.append(assistant_message)

        # Process each tool call
        for tool_call in assistant_message.tool_calls:
            if tool_call.function.name == "search_web":
                args = json.loads(tool_call.function.arguments)
                result = search_web(
                    objective=args.get("objective"),
                    search_queries=args.get("search_queries"),
                )
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result)
                })

        # Second API call with search results
        response = openai_client.chat.completions.create(
            model="gpt-5.5",
            messages=messages,
            tools=[parallel_search_tool],
            tool_choice="auto"
        )

    return response.choices[0].message.content


# Example usage
if __name__ == "__main__":
    answer = chat_with_search("What are the latest developments in quantum computing?")
    print(answer)

import OpenAI from "openai";
import Parallel from "parallel-web";

const openai = new OpenAI();
const parallel = new Parallel({ apiKey: process.env.PARALLEL_API_KEY });

// Tool definition
const parallelSearchTool: OpenAI.ChatCompletionTool = {
  type: "function",
  function: {
    name: "search_web",
    description:
      "Searches the web for current and factual information, returning relevant results with titles, URLs, and content snippets.",
    parameters: {
      type: "object",
      properties: {
        objective: {
          type: "string",
          description:
            "A concise, self-contained search query. Must include the key entity or topic being searched for.",
        },
        search_queries: {
          type: "array",
          description:
            "Exactly 3 keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles. Each query must include the key entity or topic. NEVER write sentences, instructions, or use site: operators.",
          items: { type: "string" },
          minItems: 3,
          maxItems: 3,
        },
      },
      required: ["objective", "search_queries"],
      additionalProperties: false,
    },
    strict: true,
  },
};

interface SearchArgs {
  objective?: string;
  search_queries?: string[];
}

async function searchWeb(args: SearchArgs) {
  const response = await parallel.search({
    objective: args.objective,
    search_queries: args.search_queries,
  });

  return {
    results: response.results.map((r) => ({
      url: r.url,
      title: r.title,
      excerpts: r.excerpts?.slice(0, 3) || [],
    })),
  };
}

async function chatWithSearch(userMessage: string): Promise<string | null> {
  const messages: OpenAI.ChatCompletionMessageParam[] = [
    {
      role: "system",
      content: "You are a helpful research assistant. Use the search_web tool to find current information. Always cite sources with URLs.",
    },
    { role: "user", content: userMessage },
  ];

  // First API call
  let response = await openai.chat.completions.create({
    model: "gpt-5.5",
    messages,
    tools: [parallelSearchTool],
    tool_choice: "auto",
  });

  let assistantMessage = response.choices[0].message;

  // Handle tool calls
  if (assistantMessage.tool_calls) {
    messages.push(assistantMessage);

    for (const toolCall of assistantMessage.tool_calls) {
      if (toolCall.function.name === "search_web") {
        const args = JSON.parse(toolCall.function.arguments) as SearchArgs;
        const result = await searchWeb(args);

        messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: JSON.stringify(result),
        });
      }
    }

    // Second API call with results
    response = await openai.chat.completions.create({
      model: "gpt-5.5",
      messages,
      tools: [parallelSearchTool],
      tool_choice: "auto",
    });
  }

  return response.choices[0].message.content;
}

// Example usage
async function main() {
  const answer = await chatWithSearch("What are the latest developments in quantum computing?");
  console.log(answer);
}

main().catch(console.error);

Tool Parameters

Parameter	Type	Required	Description
`objective`	string	Yes	A concise, self-contained search query. Must include the key entity or topic being searched for.
`search_queries`	string[]	Yes	Exactly 3 keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles.

This example uses the default advanced mode, which prioritizes result quality for tool use. For lower-latency responses, consider "turbo" (p50 ~200ms) or "basic". To switch, set the search mode to "turbo" inside your search_web handler. The tool schema the model sees stays unchanged. See Search Modes.

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

OpenAI Tool Calling

Overview

Prerequisites

Define the Search Tool

Implement the Search Function

Process Tool Calls

Complete Example

Tool Parameters

​Overview

​Prerequisites

​Define the Search Tool

​Implement the Search Function

​Process Tool Calls

​Complete Example

​Tool Parameters

​Related Resources

Overview

Prerequisites

Define the Search Tool

Implement the Search Function

Process Tool Calls

Complete Example

Tool Parameters

Related Resources