Tools

Not yet available. The Agent SDK is tracked to be built — today, use the Client SDKs against the live chat completions API. The docs below describe the intended design.

Tools let the model take actions — fetching data, running calculations, calling external APIs — during an agent turn. You define the schema; the model decides when and how to call the tool; the SDK dispatches the call, captures the result, and injects it into the next model request automatically.

Defining a tool#

const weatherTool = {
  name: "get_weather",
  description: "Get the current weather for a city. Returns temperature in Celsius and a short condition.",
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "City name, e.g. Algiers, Oran, Constantine.",
      },
    },
    required: ["city"],
  },
  execute: async ({ city }) => {
    const data = await fetchWeatherAPI(city);
    return `${data.tempC}°C, ${data.condition}`;
  },
};

A tool has:

• name — snake_case identifier the model uses to call the tool.
• description — plain language explanation of what the tool does and when to use it.
• parameters — JSON Schema object describing the arguments. The model uses this to construct valid calls.
• execute — async function that runs the tool and returns a string result.

Passing tools to callModel()#

const result = await client.callModel({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: "What's the weather like in Algiers today?" }],
  tools: [weatherTool],
  stopConditions: [{ type: "no_tool_calls" }],
});

console.log(result.output);

The loop continues until the stop condition is met. If the model calls get_weather, the SDK executes execute(), appends the result to the item list, and calls the model again with the result in context.

Multiple tools#

Pass an array of tools. The model can call any of them in any order, and multiple times.

tools: [weatherTool, searchTool, calculatorTool]

Tool errors#

If execute throws, the SDK catches the error, appends it as a tool_result with an error field, and lets the model decide how to respond. The agent loop does not halt on tool errors by default.

To halt on tool error, use a custom stop condition:

stopConditions: [
  {
    type: "custom",
    check: (result) => result.items.some(
      (i) => i.type === "tool_result" && i.error != null
    ),
  },
]

Parallel tool calls#

Some models issue multiple tool calls in a single turn. The SDK dispatches them concurrently using Promise.all and injects all results before calling the model again.

Tool call count#

Track tool calls across the loop via the item list:

const toolCallCount = result.items.filter((i) => i.type === "tool_call").length;

Restricting tools dynamically#

Use dynamicParams to change which tools are available mid-loop — for example, remove tools once the model has gathered enough information and should focus on producing a final answer. See Dynamic Parameters.

Tool approval#

For sensitive tools that should pause for human review before executing, add an approval function. See Tool Approval & State Persistence.

Also see#

• Tool Approval & State Persistence — human-in-the-loop approvals.
• Stop Conditions — no_tool_calls and others.
• Example: Weather Tool — a complete working example.
• API Reference — full Tool type definition.