Tool Calling

Responses API Beta

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:

responses-tool-calling-01.js


const weatherTool = {
  type: 'function' as const,
  name: 'get_weather',
  description: 'Get the current weather in a location',
  strict: null,
  parameters: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: 'The city and state, e.g. San Francisco, CA',
      },
    unit: {
      type: 'string',
      enum: ['celsius', 'fahrenheit'],
    },
},
required: ['location'],
},
};
 
const response = await fetch('https://novapai.ai/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_NOVASTACK_AI_API_KEY',
      'Content-Type': 'application/json',
    },
  body: JSON.stringify({
      model: 'openai/o4-mini',
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            {
              type: 'input_text',
              text: 'What is the weather in San Francisco?',
            },
        ],
    },
],
tools: [weatherTool],
tool_choice: 'auto',
max_output_tokens: 9000,
}),
});
 
const result = await response.json();
console.log(result);

Tool Choice Options

Control when and how tools are called:

Tool Choice	Description
`auto`	Model decides whether to call tools
`none`	Model will not call any tools
`\{type: 'function', name: 'tool_name'\}`	Force specific tool call

Force Specific Tool

responses-tool-calling-02.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Hello, how are you?",
          },
        ],
      },
    ],
    tools: [weatherTool],
    tool_choice: { type: "function", name: "get_weather" },
    max_output_tokens: 9000,
  }),
});

Disable Tool Calling

responses-tool-calling-03.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "What is the weather in Paris?",
          },
        ],
      },
    ],
    tools: [weatherTool],
    tool_choice: "none",
    max_output_tokens: 9000,
  }),
});

Multiple Tools

Define multiple tools for complex workflows:

responses-tool-calling-04.js


const calculatorTool = {
  type: 'function' as const,
  name: 'calculate',
  description: 'Perform mathematical calculations',
  strict: null,
  parameters: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: 'The mathematical expression to evaluate',
      },
  },
required: ['expression'],
},
};
 
const response = await fetch('https://novapai.ai/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_NOVASTACK_AI_API_KEY',
      'Content-Type': 'application/json',
    },
  body: JSON.stringify({
      model: 'openai/o4-mini',
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            {
              type: 'input_text',
              text: 'What is 25 * 4?',
            },
        ],
    },
],
tools: [weatherTool, calculatorTool],
tool_choice: 'auto',
max_output_tokens: 9000,
}),
});

Parallel Tool Calls

The API supports parallel execution of multiple tools:

responses-tool-calling-05.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Calculate 10*5 and also tell me the weather in Miami",
          },
        ],
      },
    ],
    tools: [weatherTool, calculatorTool],
    tool_choice: "auto",
    max_output_tokens: 9000,
  }),
});
 
const result = await response.json();
console.log(result);

Tool Call Response

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

responses-tool-calling-06.json


{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "openai/o4-mini",
  "output": [
    {
      "type": "function_call",
      "id": "fc_abc123",
      "call_id": "call_xyz789",
      "name": "get_weather",
      "arguments": "{\"location\":\"San Francisco, CA\"}"
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 25,
    "total_tokens": 70
  },
  "status": "completed"
}

Tool Responses in Conversation

Include tool responses in follow-up requests:

responses-tool-calling-07.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "What is the weather in Boston?",
          },
        ],
      },
      {
        type: "function_call",
        id: "fc_1",
        call_id: "call_123",
        name: "get_weather",
        arguments: JSON.stringify({ location: "Boston, MA" }),
      },
      {
        type: "function_call_output",
        id: "fc_output_1",
        call_id: "call_123",
        output: JSON.stringify({ temperature: "72°F", condition: "Sunny" }),
      },
      {
        type: "message",
        role: "assistant",
        id: "msg_abc123",
        status: "completed",
        content: [
          {
            type: "output_text",
            text: "The weather in Boston is currently 72°F and sunny. This looks like perfect weather for a picnic!",
            annotations: [],
          },
        ],
      },
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Is that good weather for a picnic?",
          },
        ],
      },
    ],
    max_output_tokens: 9000,
  }),
});

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:

responses-tool-calling-08.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "What is the weather like in Tokyo, Japan? Please check the weather.",
          },
        ],
      },
    ],
    tools: [weatherTool],
    tool_choice: "auto",
    stream: true,
    max_output_tokens: 9000,
  }),
});
 
const reader = response.body?.getReader();
const decoder = new TextDecoder();
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const chunk = decoder.decode(value);
  const lines = chunk.split("\n");
 
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = line.slice(6);
      if (data === "[DONE]") return;
 
      try {
        const parsed = JSON.parse(data);
        if (
          parsed.type === "response.output_item.added" &&
          parsed.item?.type === "function_call"
        ) {
          console.log("Function call:", parsed.item.name);
        }
        if (parsed.type === "response.function_call_arguments.done") {
          console.log("Arguments:", parsed.arguments);
        }
      } catch (e) {
        // Skip invalid JSON
      }
    }
  }
}

Tool Validation

Ensure tool calls have proper structure:

responses-tool-calling-09.json


{
  "type": "function_call",
  "id": "fc_abc123",
  "call_id": "call_xyz789",
  "name": "get_weather",
  "arguments": "{\"location\":\"Seattle, WA\"}"
}

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


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

Next Steps

Learn about Web Search integration
Explore Reasoning with tools
Review Basic Usage fundamentals