Tool Calling

Learn how to use tool calling (also known as function calling) with the June API, and how to leverage June's hosted tools.

How Tool Calling Works

Tool calling lets a model interact with external functions and data sources. The model doesn't call tools directly — instead, it tells you which tool it wants to call and with what arguments. You execute the tool, return the result, and the model uses it to form its final response.

The flow has four steps:

  1. Send a request with tools defined — you include a list of tools the model can use, alongside the user's message.
  2. Receive a tool call — the model responds with a tool_calls array instead of a regular message, specifying the function name and arguments.
  3. Execute the tool — your code runs the function with the provided arguments and collects the result.
  4. Return the result — you send the tool output back to the model, which uses it to generate a final response.

Example

Tools are defined in the tools parameter using a type, name, description, and a parameters object that follows JSON Schema. Write clear, descriptive function names and parameter descriptions — this helps the model understand when and how to use each tool.

Here's a complete tool calling flow.

# Step 1: Send a request with tools
curl https://api.blockchain.info/ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JUNE_API_KEY" \
  -d '{
    "model": "blockchain/june",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City and country, e.g. Paris, France"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

# The model responds with a tool call:
# {
#   "choices": [{
#     "message": {
#       "role": "assistant",
#       "tool_calls": [{
#         "id": "call_abc123",
#         "type": "function",
#         "function": {
#           "name": "get_weather",
#           "arguments": "{\"location\": \"Paris, France\"}"
#         }
#       }]
#     },
#     "finish_reason": "tool_calls"
#   }]
# }

# Step 2: Execute the tool and return the result
curl https://api.blockchain.info/ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JUNE_API_KEY" \
  -d '{
    "model": "blockchain/june",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris?" },
      {
        "role": "assistant",
        "tool_calls": [{
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"Paris, France\"}"
          }
        }]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": \"18\", \"unit\": \"C\", \"condition\": \"Partly cloudy\"}"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City and country, e.g. Paris, France"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

# The model responds with a final answer:
# "The weather in Paris is 18°C and partly cloudy."

Tool Choice

By default the model decides whether to use tools. You can control this with the tool_choice parameter:

  • "auto" — (default) the model decides whether to call tools.
  • "none" — disable tool calling for this request.
  • "required" — force the model to call at least one tool.
  • {"type": "function", "function": {"name": "get_weather"}} — force a specific tool.

Parallel Tool Calls

The model may call multiple tools in a single turn. Each tool call will have its own id, and you should return a result for each one. To restrict the model to one tool call at a time, set parallel_tool_calls to false.

June Hosted Tools

June provides a set of hosted tools that you can use out of the box — no need to implement the tool logic yourself.

Listing Available Tools

Retrieve the list of hosted tools from the /v1/tools endpoint. The response uses the OpenAI-compatible tool format, so you can pass the tools directly into a chat completion request.

curl https://api.blockchain.info/ai/api/v1/tools \
  -H "Authorization: Bearer $JUNE_API_KEY"

Executing a Tool

To execute a hosted tool, call POST /v1/tools/{toolName} with the tool arguments as the request body. The response contains the tool output, which you can return to the model as a tool message.

# Execute a hosted tool call
curl -X POST https://api.blockchain.info/ai/api/v1/tools/get_weather \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JUNE_API_KEY" \
  -d '{"location": "Paris, France"}'

Automatic Tool Execution

If you don't want to handle the tool execution loop yourself, you can set the execute_tools parameter to true in your chat completion request. When enabled, June will automatically inject its hosted tools, execute any tool calls the model makes, and return the final response — no tool definitions or manual execution needed.

curl https://api.blockchain.info/ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JUNE_API_KEY" \
  -d '{
    "model": "blockchain/june",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris?" }
    ],
    "execute_tools": true
  }'