Tool calling in JavaScript, explained with one example

Tool calling (also called function calling) lets a language model ask your code to run a function. You describe the function to the model with a name, a description and a JSON schema. When the model decides it needs the function, it replies with the function's name and arguments instead of text. Your code runs it, sends the result back, and calls the model a second time to get the final answer. The model never runs anything itself.

What does a tool look like?

A tool is a normal JavaScript function plus a description the model can read. The description has three parts: a name, a sentence about when to use it, and a JSON schema for its arguments.

1const tools = [

2 {

3 type: "function",

4 function: {

5 name: "getOrder",

6 description: "Get an order's status by order ID. Use when the user asks where an order is.",

7 parameters: {

8 type: "object",

9 properties: { id: { type: "string" } },

10 required: ["id"],

11 },

12 },

13 },

14];

The description matters more than it looks. It is the model's only clue about when to use the tool. "Gets order data" leads to wrong choices. "Use when the user asks where an order is" doesn't. Rewriting a vague description is often the whole fix when an agent picks the wrong tool (tool description lesson).

What does the model send back?

Send the tools along with the conversation. If the model wants a tool, the reply has no text. It has a tool_calls list instead.

1const response = await client.chat.completions.create({

2 model,

3 messages: [{ role: "user", content: "Where is order A12?" }],

4 tools,

5});

6

7const message = response.choices[0].message;

8// message.content is null

9// message.tool_calls[0].function.name is "getOrder"

10// message.tool_calls[0].function.arguments is '{"id":"A12"}'

Notice that arguments is a string of JSON, not an object. You have to parse it, and it can be malformed or simply wrong (arguments lesson).

How do I run the tool safely?

Parse the arguments, then check them before you run anything. The model can send a value that is out of range, or one that someone smuggled into the conversation on purpose. Zod makes the check one line.

1import { z } from "zod";

2

3const GetOrderArguments = z.object({ id: z.string().min(1).max(20) });

4

5const call = message.tool_calls[0];

6const parsed = GetOrderArguments.safeParse(JSON.parse(call.function.arguments));

7const result = parsed.success ? await getOrder(parsed.data.id) : { error: "Invalid order ID" };

Sending an error back to the model is usually better than throwing. The model reads it and can try again with better arguments. Treat every tool argument like req.body: untrusted until checked (validation lesson).

How do I send the result back?

Add two messages to the conversation, in this order:

1. The model's own message with the tool_calls, unchanged.
2. A message with role: "tool", the tool_call_id from the call, and the result as a string.

1messages.push(message);

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

The tool_call_id links the answer to the request, like a reply in the right email thread (tool message lesson).

Why does it take two model calls?

The first call decides which tool to use. The second call, with the result now in the messages, writes the answer for the user.

1const followUp = await client.chat.completions.create({ model, messages, tools });

2console.log(followUp.choices[0].message.content);

3// "Order A12 shipped yesterday and should arrive on Friday."

Keep passing tools on the second call. The model might need a second tool before it can answer, and that is how a single round trip grows into an agent. Put this in a loop and you have the agent loop.

Can the model call several tools at once?

Yes. One reply can hold several entries in tool_calls. Run them together with Promise.all, then add one tool message per call. OpenAI's guide says the model "may choose to call multiple functions in a single turn", and you can turn that off with parallel_tool_calls: false (function calling guide).

You can also steer tool use with tool_choice. The default "auto" lets the model decide, "none" forbids tools, "required" forces one, and naming a function forces that function.

Chat Completions or Responses API?

Everything above uses Chat Completions, which OpenAI says "remains supported". For new projects OpenAI recommends the Responses API, and some of its newest models need Responses for tool calling (migration guide). The steps are the same, with different names:

If you understand one, you understand both.

Practise it

The tool calling part breaks this into ten cards, from the schema to parallel calls. In the app, Quiz shows you real tool-calling code and asks what it returns before you see the answer. That is the fastest way to find out whether you really know where arguments stops being a string.