AI

Call tools

Let a model ask your code to run a function, such as looking up an order, then answer with the result.

A model can ask your code to run a tool you describe, such as a function that looks up an order. Your code runs it and sends the result back, and the model answers with it. Every model in Models marked for tools can do this.

Describe your tools

Send tools with the conversation. Each tool has a name, a description, and its parameters as JSON Schema.

const tools = [
  {
    type: "function" as const,
    function: {
      name: "order_status",
      description: "Look up where an order is, by its number.",
      parameters: {
        type: "object",
        properties: {
          order: { type: "string", description: "The order number" },
        },
        required: ["order"],
      },
    },
  },
]

const messages = [{ role: "user" as const, content: "Where is order 4815?" }]

const first = await client.chat.completions.create({
  model: "openai/gpt-oss-120b",
  messages,
  tools,
})

Run the tool, then send the result

When the model wants a tool, its message holds tool_calls instead of text. Run each one, and answer with a tool message that names the call it answers:

const asked = first.choices[0].message
messages.push(asked)

for (const call of asked.tool_calls ?? []) {
  const { order } = JSON.parse(call.function.arguments)
  const status = await lookUpOrder(order)
  messages.push({
    role: "tool",
    tool_call_id: call.id,
    content: JSON.stringify(status),
  })
}

const answer = await client.chat.completions.create({
  model: "openai/gpt-oss-120b",
  messages,
  tools,
})

console.log(answer.choices[0].message.content)

Rules for tools

  • Only assistant messages hold tool_calls, and every tool message needs the tool_call_id it answers.
  • tool_choice needs tools. Use it to make the model call a tool, or none.
  • Check the arguments before you act on them. The model writes them, so treat them like any other input.
  • Tool descriptions and results count toward the model’s input tokens, and so toward your units.

Last updated