How it works

The explanation, with examples you can run.

The loop

Send the conversation plus tool definitions.
If the response asks for one or more tool calls (providers mark this with a stop reason such as tool_use or a tool_calls field), validate the arguments, run each tool, and append a result message that references the call's id.
Call the model again with the extended conversation.
Repeat until the model replies with a final answer, or until your own limit stops it.

The Try it block plays this loop with a scripted fake model, so you can see exactly which messages travel each way.

Your code

const tools = {
  get_order: ({ order_id }) => {
    const orders = { "A-1001": { status: "shipped", eta: "Thursday" } }
    if (!orders[order_id]) throw new Error(`No order ${order_id}`)
    return orders[order_id]
  },
}

// Scripted model: first asks for a tool, then answers using the result it was sent.
function fakeModel(messages) {
  const last = messages[messages.length - 1]
  if (last.role === "user") {
    return { stop: "tool_use", calls: [{ id: "call_1", name: "get_order", args: { order_id: "A-1001" } }] }
  }
  const result = JSON.parse(last.content)
  return { stop: "end", text: `Your order has ${result.status} and should arrive ${result.eta}.` }
}

function runTool(call) {
  if (!(call.name in tools)) return { is_error: true, content: `Unknown tool ${call.name}` }
  try {
    return { is_error: false, content: JSON.stringify(tools[call.name](call.args)) }
  } catch (e) {
    return { is_error: true, content: e.message }
  }
}

const messages = [{ role: "user", content: "Where is my order A-1001?" }]
for (let round = 1; round <= 5; round++) {
  const res = fakeModel(messages)
  if (res.stop !== "tool_use") {
    console.log("final answer:", res.text)
    break
  }
  messages.push({ role: "assistant", tool_calls: res.calls })
  for (const call of res.calls) {
    console.log(`round ${round}: model asks ${call.name}(${JSON.stringify(call.args)})`)
    const out = runTool(call)
    console.log(`round ${round}: we send back`, out.content)
    messages.push({ role: "tool", tool_call_id: call.id, ...out })
  }
}
console.log("messages exchanged:", messages.length)

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

Designing tools

Descriptions are prompts. Say what the tool does, when to use it and when not to, and what each argument means, with formats ("ISO 8601 date", "order id like A-1234").
Few, clear tools beat many overlapping ones. If two tools could both answer a question, the model will sometimes choose the wrong one. Merge or rename them.
Return what the model needs, not everything you have. Trim large responses; tool results count as input tokens on the next call.
Make side effects explicit. Separate read tools from write tools. For writes that matter (payments, emails, deletions), require confirmation from the user or a human, and make them idempotent so a repeated call does no harm.
Several calls at once. Many APIs let the model request several independent tool calls in one turn. Run them concurrently if they are independent, and return every result.

Your code is the security boundary

The arguments come from a model whose input may include user text and retrieved documents, so treat them exactly like a request from an untrusted client: validate against the schema, check the current user's permissions, apply rate limits, and log what ran. Never let the model choose which credentials to use; give tools only the access they need. A prompt can describe rules, but only code enforces them.

1// Placeholder client and types; the shape is common across providers.2let messages: Message[] = [{ role: "user", content: question }]3for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {4  const res = await llm.generate({ model: MODEL, system: SYSTEM, tools: TOOL_DEFINITIONS, messages })5  if (res.stopReason !== "tool_use") return res.text6  messages = [...messages, res.asAssistantMessage()]7  const results = await Promise.all(res.toolCalls.map((call) => runToolSafely(call, currentUser)))8  messages = [...messages, toolResultMessage(results)]9}10throw new Error("Tool loop did not finish")

Check yourself

3 questions. Get them all right to finish this topic.

1.The model returns a tool call: get_order({ order_id: "A-1001" }). What happens next?
2.A tool throws because the order does not exist. What is usually the best thing to send back?
3.Why put the user's permissions check in your tool code rather than in the prompt?

0 of 3 right so far. Get all three to finish this topic.

Tool use: the model asks, your code runs

How it works

The loop

Designing tools

Your code is the security boundary

Check yourself

Go deeper