> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Calling

> Define tools the model can call and build multi-turn agentic loops with the Messages API

The Messages API supports tool calling to give Claude models access to external functions. Define tools using the Anthropic `input_schema` format. When the model wants to use a tool, it returns a `tool_use` content block with `stop_reason: "tool_use"`.

<Warning>
  The Messages API (`/v1/messages`) is fully supported on the **Enterprise plan** using `https://enterprise.blackbox.ai`. On standard plans (`https://api.blackbox.ai`), this endpoint may not work as expected. For the best experience, use an Enterprise API key.
</Warning>

<Warning>
  **Important — Tool Format**: The Messages API uses `input_schema` for tool parameter definitions. This is different from the Responses API which uses `parameters`. Using the wrong format will result in errors.
</Warning>

<Tip>
  See [API Best Practices](/api-reference/best-practices) for how to correctly structure tool call IDs, pair every tool call with a tool result, [preserve thinking signatures](/api-reference/best-practices#avoiding-invalid-thinking-signatures), and [avoid thinking + forced tool\_choice conflicts](/api-reference/best-practices#avoiding-thinking-with-forced-tool-choice).
</Tip>

## Basic Tool Calling

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  response = requests.post(
      'https://enterprise.blackbox.ai/v1/messages',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
          'anthropic-version': '2023-06-01',
      },
      json={
          'model': 'blackboxai/anthropic/claude-sonnet-4.5',
          'max_tokens': 1024,
          'tools': [
              {
                  'name': 'get_weather',
                  'description': 'Get current weather for a city',
                  'input_schema': {
                      'type': 'object',
                      'properties': {
                          'city': {'type': 'string', 'description': 'City name'}
                      },
                      'required': ['city'],
                  },
              }
          ],
          'messages': [
              {'role': 'user', 'content': "What's the weather in Paris?"}
          ],
      },
  )

  result = response.json()
  print(result['stop_reason'])  # "tool_use"
  for block in result['content']:
      if block['type'] == 'tool_use':
          print(f"Tool: {block['name']}, Input: {block['input']}")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "anthropic-version": "2023-06-01"
    },
    body: JSON.stringify({
      model: "blackboxai/anthropic/claude-sonnet-4.5",
      max_tokens: 1024,
      tools: [{
        name: "get_weather",
        description: "Get current weather for a city",
        input_schema: {
          type: "object",
          properties: {
            city: { type: "string", description: "City name" }
          },
          required: ["city"]
        }
      }],
      messages: [
        { role: "user", content: "What's the weather in Paris?" }
      ]
    })
  });

  const result = await response.json();
  console.log(result.stop_reason); // "tool_use"
  for (const block of result.content) {
    if (block.type === "tool_use") {
      console.log(`Tool: ${block.name}, Input:`, block.input);
    }
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl https://enterprise.blackbox.ai/v1/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "blackboxai/anthropic/claude-sonnet-4.5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get current weather for a city",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }],
      "messages": [
        {"role": "user", "content": "What is the weather in Paris?"}
      ]
    }'
  ```
</CodeGroup>

## Tool Call Response

When the model wants to call a tool, the response has `stop_reason: "tool_use"` and includes `tool_use` content blocks:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "gen_01KJRNF3KKH18317Z4441HVH1V",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01DFdL9a3hM7jjbaTRHYSYoy",
      "name": "get_weather",
      "input": {
        "city": "Paris"
      }
    }
  ],
  "model": "blackboxai/anthropic/claude-sonnet-4.5",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 591,
    "output_tokens": 53
  }
}
```

## Handling Tool Results

After receiving a `tool_use` response, execute the tool locally and send the result back. The assistant's full response becomes the next `assistant` message, and your tool result goes in a `user` message:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # After getting the tool_use response above...
  tool_use_block = next(b for b in result["content"] if b["type"] == "tool_use")

  # Execute the tool locally
  weather_data = get_weather(tool_use_block["input"]["city"])

  # Send the result back to continue the conversation
  messages = [
      {"role": "user", "content": "What's the weather in Paris?"},
      {"role": "assistant", "content": result["content"]},
      {"role": "user", "content": [
          {
              "type": "tool_result",
              "tool_use_id": tool_use_block["id"],
              "content": weather_data
          }
      ]}
  ]

  body = {
      "model": "blackboxai/anthropic/claude-sonnet-4.5",
      "max_tokens": 1024,
      "tools": tools,
      "messages": messages
  }

  # The model now uses the tool result to generate a final answer
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // After getting the tool_use response above...
  const toolUseBlock = result.content.find((b: any) => b.type === "tool_use");

  // Execute the tool locally
  const weatherData = getWeather(toolUseBlock.input.city);

  // Send the result back to continue the conversation
  const messages = [
    { role: "user", content: "What's the weather in Paris?" },
    { role: "assistant", content: result.content },
    { role: "user", content: [
      {
        type: "tool_result",
        tool_use_id: toolUseBlock.id,
        content: weatherData
      }
    ]}
  ];
  ```
</CodeGroup>

The model then uses the tool result to generate a natural language response:

```json Final Answer Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "gen_01KJRNF6ABJA4J76NWMMRVYMFT",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The weather in Paris is currently sunny with a temperature of 22°C. It's a beautiful day!"
    }
  ],
  "model": "blackboxai/anthropic/claude-sonnet-4.5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 637,
    "output_tokens": 31
  }
}
```

***

## Multiple Tools

You can define multiple tools and the model will call whichever ones it needs — including calling multiple tools in a single response (parallel tool calls):

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  response = requests.post(
      'https://enterprise.blackbox.ai/v1/messages',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
          'anthropic-version': '2023-06-01',
      },
      json={
          'model': 'blackboxai/anthropic/claude-sonnet-4.5',
          'max_tokens': 1024,
          'tools': [
              {
                  'name': 'get_weather',
                  'description': 'Get current weather for a city',
                  'input_schema': {
                      'type': 'object',
                      'properties': {
                          'city': {'type': 'string', 'description': 'City name'}
                      },
                      'required': ['city'],
                  },
              },
              {
                  'name': 'get_time',
                  'description': 'Get current local time in a city',
                  'input_schema': {
                      'type': 'object',
                      'properties': {
                          'city': {'type': 'string', 'description': 'City name'}
                      },
                      'required': ['city'],
                  },
              },
          ],
          'messages': [
              {'role': 'user', 'content': "What's the weather and time in Tokyo?"}
          ],
      },
  )

  result = response.json()

  # The model may call multiple tools at once
  for block in result['content']:
      if block['type'] == 'tool_use':
          print(f"Tool: {block['name']}, Input: {block['input']}")
      elif block['type'] == 'text':
          print(f"Text: {block['text']}")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const response = await fetch("https://enterprise.blackbox.ai/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "anthropic-version": "2023-06-01"
    },
    body: JSON.stringify({
      model: "blackboxai/anthropic/claude-sonnet-4.5",
      max_tokens: 1024,
      tools: [
        {
          name: "get_weather",
          description: "Get current weather for a city",
          input_schema: {
            type: "object",
            properties: { city: { type: "string" } },
            required: ["city"]
          }
        },
        {
          name: "get_time",
          description: "Get current local time in a city",
          input_schema: {
            type: "object",
            properties: { city: { type: "string" } },
            required: ["city"]
          }
        }
      ],
      messages: [
        { role: "user", content: "What's the weather and time in Tokyo?" }
      ]
    })
  });

  const result = await response.json();
  for (const block of result.content) {
    if (block.type === "tool_use") console.log(`Tool: ${block.name}`, block.input);
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl https://enterprise.blackbox.ai/v1/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "blackboxai/anthropic/claude-sonnet-4.5",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Get current weather for a city",
          "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        },
        {
          "name": "get_time",
          "description": "Get current local time in a city",
          "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      ],
      "messages": [
        {"role": "user", "content": "What is the weather and time in Tokyo?"}
      ]
    }'
  ```
</CodeGroup>

The model calls both tools in a single response:

```json Response — Parallel Tool Calls theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "gen_01KJRNF8P97RJAYQPX6J9ASV8R",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll get the current weather and time in Tokyo for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WMNa2FQJw199bNLS2rJiK4",
      "name": "get_weather",
      "input": { "city": "Tokyo" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01BUTXWBVKJqrumPzi2zTLvL",
      "name": "get_time",
      "input": { "city": "Tokyo" }
    }
  ],
  "model": "blackboxai/anthropic/claude-sonnet-4.5",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 617,
    "output_tokens": 103
  }
}
```

<Note>
  When the model makes parallel tool calls, you must provide a `tool_result` for **every** `tool_use` block in the response. Send all results in a single `user` message.
</Note>

***

## Multi-Turn Tool Calling

For multi-turn conversations with tools, pass the assistant's response (including `tool_use` blocks) back as an `assistant` message, followed by a `user` message containing `tool_result` blocks. Continue the loop until `stop_reason` is `"end_turn"`.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import os
  import requests

  url = 'https://enterprise.blackbox.ai/v1/messages'
  headers = {
      'Content-Type': 'application/json',
      'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
      'anthropic-version': '2023-06-01',
  }

  tools = [{
      'name': 'calculator',
      'description': 'Perform arithmetic operations',
      'input_schema': {
          'type': 'object',
          'properties': {
              'operation': {'type': 'string', 'description': 'add, subtract, multiply, divide'},
              'a': {'type': 'number'},
              'b': {'type': 'number'},
          },
          'required': ['operation', 'a', 'b'],
      },
  }]

  def calculate(operation, a, b):
      ops = {'add': a + b, 'subtract': a - b, 'multiply': a * b, 'divide': a / b}
      return str(ops.get(operation, 'Unknown'))

  messages = [
      {'role': 'user', 'content': 'Calculate (15 + 27) * 3. Do addition first, then multiply.'}
  ]

  # Agentic loop
  for turn in range(10):
      result = requests.post(url, headers=headers, json={
          'model': 'blackboxai/anthropic/claude-sonnet-4.5',
          'max_tokens': 4000,
          'system': 'Use the calculator tool for each step.',
          'tools': tools,
          'messages': messages,
      }).json()

      # Done — model returned final text
      if result['stop_reason'] == 'end_turn':
          for block in result['content']:
              if block['type'] == 'text':
                  print(f"Final answer: {block['text']}")
          break

      # Model wants to use tools — execute them
      if result['stop_reason'] == 'tool_use':
          # Add assistant response to conversation
          messages.append({'role': 'assistant', 'content': result['content']})

          # Execute each tool call and collect results
          tool_results = []
          for block in result['content']:
              if block['type'] == 'tool_use':
                  answer = calculate(**block['input'])
                  tool_results.append({
                      'type': 'tool_result',
                      'tool_use_id': block['id'],
                      'content': answer,
                  })

          # Send tool results back
          messages.append({'role': 'user', 'content': tool_results})
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const url = "https://enterprise.blackbox.ai/v1/messages";
  const headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "anthropic-version": "2023-06-01"
  };

  const tools = [{
    name: "calculator",
    description: "Perform arithmetic operations",
    input_schema: {
      type: "object",
      properties: {
        operation: { type: "string" },
        a: { type: "number" },
        b: { type: "number" }
      },
      required: ["operation", "a", "b"]
    }
  }];

  function calculate(op: string, a: number, b: number): string {
    const ops: Record<string, number> = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
    return String(ops[op] ?? "Unknown");
  }

  const messages: any[] = [
    { role: "user", content: "Calculate (15 + 27) * 3. Do addition first, then multiply." }
  ];

  for (let turn = 0; turn < 10; turn++) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify({
        model: "blackboxai/anthropic/claude-sonnet-4.5",
        max_tokens: 4000,
        system: "Use the calculator tool for each step.",
        tools,
        messages
      })
    });

    const result = await response.json();

    if (result.stop_reason === "end_turn") {
      for (const block of result.content) {
        if (block.type === "text") console.log("Final:", block.text);
      }
      break;
    }

    if (result.stop_reason === "tool_use") {
      messages.push({ role: "assistant", content: result.content });

      const toolResults = result.content
        .filter((b: any) => b.type === "tool_use")
        .map((b: any) => ({
          type: "tool_result",
          tool_use_id: b.id,
          content: calculate(b.input.operation, b.input.a, b.input.b)
        }));

      messages.push({ role: "user", content: toolResults });
    }
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Step 1: Initial request
  curl https://enterprise.blackbox.ai/v1/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "blackboxai/anthropic/claude-sonnet-4.5",
      "max_tokens": 4000,
      "system": "Use the calculator tool for each step.",
      "tools": [{
        "name": "calculator",
        "description": "Perform arithmetic",
        "input_schema": {
          "type": "object",
          "properties": {
            "operation": {"type": "string"},
            "a": {"type": "number"},
            "b": {"type": "number"}
          },
          "required": ["operation", "a", "b"]
        }
      }],
      "messages": [
        {"role": "user", "content": "Calculate (15 + 27) * 3. Do addition first."}
      ]
    }'

  # Step 2: Pass back tool_use content as assistant message + tool_result as user message
  # Repeat until stop_reason is "end_turn"
  ```
</CodeGroup>

## Multi-Turn Conversation Flow

Here's how the message array builds up across turns:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
[
  // Turn 1: User asks a question
  {"role": "user", "content": "Calculate (15 + 27) * 3"},

  // Turn 1: Assistant calls a tool
  {"role": "assistant", "content": [
    {"type": "text", "text": "Let me start with the addition."},
    {"type": "tool_use", "id": "toolu_01ABC...", "name": "calculator", "input": {"operation": "add", "a": 15, "b": 27}}
  ]},

  // Turn 2: You provide the tool result
  {"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01ABC...", "content": "42"}
  ]},

  // Turn 2: Assistant calls another tool
  {"role": "assistant", "content": [
    {"type": "text", "text": "Now let me multiply by 3."},
    {"type": "tool_use", "id": "toolu_02DEF...", "name": "calculator", "input": {"operation": "multiply", "a": 42, "b": 3}}
  ]},

  // Turn 3: You provide the tool result
  {"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": "toolu_02DEF...", "content": "126"}
  ]}

  // Turn 3: Assistant returns final answer with stop_reason: "end_turn"
]
```

<Note>
  Each `tool_result` must reference the `tool_use_id` from the corresponding `tool_use` block. The API will return an error if the IDs don't match.
</Note>

## Tool Definition Format

Tools use the Anthropic `input_schema` format:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "name": "tool_name",
  "description": "What this tool does",
  "input_schema": {
    "type": "object",
    "properties": {
      "param1": {"type": "string", "description": "Parameter description"},
      "param2": {"type": "number"}
    },
    "required": ["param1"]
  }
}
```

| Field          | Type   | Required | Description                                                |
| -------------- | ------ | :------: | ---------------------------------------------------------- |
| `name`         | string |     ✓    | Unique tool name                                           |
| `description`  | string |     ✓    | What the tool does — helps the model decide when to use it |
| `input_schema` | object |     ✓    | JSON Schema for the tool's parameters                      |

<CardGroup cols={3}>
  <Card title="Interleaved Thinking" icon="brain" href="/api-reference/messages/interleaved-thinking">
    Add reasoning between tool calls
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/api-reference/best-practices">
    Tool call IDs, pairing tool results, thinking signatures, and more
  </Card>

  <Card title="Messages API Overview" icon="book" href="/api-reference/messages/introduction">
    Headers, parameters, and supported models
  </Card>
</CardGroup>