SetCloud
✦ Ask AI Get started

Tool calling

Tool calling lets a model ask your code to run a function instead of trying to answer from what it already knows. This page covers declaring tools, handling the model’s request to call one, returning the result, and looping until you have a final answer.

Declaring tools

Pass a tools array on POST /v1/chat/completions, each entry a JSON-schema function definition — a name, a description, and its parameters:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Current weather for a city",
    "parameters": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  }
}

Handling tool_calls

When the model decides to call one, the response’s assistant message carries tool_calls instead of text — content is null, and finish_reason is "tool_calls". Each entry in tool_calls names the function and the arguments the model wants to call it with, as a JSON string.

Returning tool results

Append the assistant message from the previous response to your conversation, then add one tool message per call, each carrying the matching tool_call_id and the function’s result as a string. Send the whole conversation back to the same endpoint.

Multi-turn loops

A model can chain several tool calls before it has enough to answer — run each one, append its result, and call the endpoint again. Keep looping while finish_reason comes back "tool_calls"; once it comes back "stop", the assistant message holds your final answer.

Next