Claude API Tool Use: Multiple Tools Example Guide

Claude API Tool Use: Multiple Tools Example

When you give Claude more than one tool in the same request, it doesn't just pick one and stop — it can call several tools in a single turn, in parallel, if the task calls for it. This article walks through a complete working example: defining multiple tools, understanding how Claude decides which ones to use, and correctly handling a response that contains more than one tool_use block.

The short answer to "how do I use multiple tools with the Claude API" is: pass an array of tool definitions in the tools parameter, let Claude return zero, one, or several tool_use content blocks in its response, execute each one, and send all the results back together in a single user message with matching tool_result blocks. The rest of this guide shows exactly how that works in practice.

Defining multiple tools in one request

Each tool needs a name, a description, and an input_schema. Claude relies heavily on the description to decide when to use a tool, so be specific about what each one does and when it should (or shouldn't) be called.

{
  "model": "claude-opus-4-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a given city",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      }
    },
    {
      "name": "get_stock_price",
      "description": "Get the current stock price for a ticker symbol",
      "input_schema": {
        "type": "object",
        "properties": {
          "ticker": { "type": "string" }
        },
        "required": ["ticker"]
      }
    },
    {
      "name": "convert_currency",
      "description": "Convert an amount from one currency to another using current exchange rates",
      "input_schema": {
        "type": "object",
        "properties": {
          "amount": { "type": "number" },
          "from": { "type": "string" },
          "to": { "type": "string" }
        },
        "required": ["amount", "from", "to"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What's the weather in Tokyo and what's AAPL trading at right now?"
    }
  ]
}

With three tools available and a question that touches two of them, Claude will typically return two tool_use blocks in a single response rather than asking a follow-up question or guessing.

What a multi-tool response looks like

The content array in Claude's reply can contain multiple tool_use blocks alongside optional text:

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "I'll check both for you." },
    {
      "type": "tool_use",
      "id": "toolu_01A",
      "name": "get_weather",
      "input": { "city": "Tokyo" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01B",
      "name": "get_stock_price",
      "input": { "ticker": "AAPL" }
    }
  ],
  "stop_reason": "tool_use"
}

This is parallel tool use: Claude recognized two independent requests and issued both calls at once instead of serializing them turn by turn. That matters for latency — you can execute both tool calls concurrently in your application code.

Handling the response and sending results back

You need to loop over every tool_use block, execute the corresponding function, and return a tool_result for each one, matched by tool_use_id. All results go into a single user message.

const toolUseBlocks = response.content.filter(b => b.type === "tool_use");

const results = await Promise.all(
  toolUseBlocks.map(async (block) => {
    let output;
    if (block.name === "get_weather") {
      output = await getWeather(block.input.city);
    } else if (block.name === "get_stock_price") {
      output = await getStockPrice(block.input.ticker);
    } else if (block.name === "convert_currency") {
      output = await convertCurrency(block.input);
    }
    return {
      type: "tool_result",
      tool_use_id: block.id,
      content: JSON.stringify(output)
    };
  })
);

messages.push({ role: "assistant", content: response.content });
messages.push({ role: "user", content: results });

A common mistake is sending only the first tool_use_id back or putting each tool_result in a separate message. Claude expects all results for a given turn bundled into one user message, in any order, each tagged with the correct tool_use_id.

Controlling which tools get used

If you want to force Claude to pick from your tool set (or use one specifically), the tool_choice parameter gives you three modes:

• {"type": "auto"} — default behavior, Claude decides whether and which tools to call
• {"type": "any"} — Claude must call at least one tool, but can choose which
• {"type": "tool", "name": "get_weather"} — forces a specific tool

auto is what enables multi-tool parallel calls naturally. If you force a single named tool, Claude will only call that one, even if the prompt implies others are relevant.

Tips for reliable multi-tool setups

• Keep tool names and descriptions unambiguous. If two tools have overlapping purposes (e.g., get_weather and get_forecast), Claude may pick the wrong one or call both unnecessarily.
• Limit the active tool list per request. Passing 20+ tools when only 3 are relevant increases the chance of misfires. Filter server-side based on context before sending the request.
• Validate input against your schema before executing. Claude follows input_schema closely but your code should not assume it's always perfectly shaped, especially with optional fields.
• Watch stop_reason. A value of tool_use means Claude is waiting on results — don't treat the turn as finished until you've sent tool_result blocks back.

If you're building this against your existing Claude access rather than a raw Anthropic account, SubToAPI exposes the same tool-use request format over a standard API key (sub_live_...), so this example works unchanged against https://api.subtoapi.app/v1/messages. See /docs/tools for the full reference and /docs/messages for request/response shapes, or start with the quickstart if you're new to the setup.

FAQ

Can Claude call more than two tools in a single response? Yes. There's no hard limit on the number of tool_use blocks in one response — it depends entirely on how many distinct tool calls the prompt genuinely requires.

Do I have to execute tool calls in the order Claude returns them? No. Tool calls in a single turn are independent of each other, so you can execute them in parallel and return the results in any order, as long as each tool_result references the correct tool_use_id.

What happens if I only return a result for one of several tool calls? Claude will treat the turn as incomplete or may error depending on the SDK, since it's waiting on results for every tool_use_id it issued. Always respond to all of them in the same message.