Tool Calling

Tool calling in ASI:One allows models to go beyond text generation by invoking external functions with the right parameters. This enables integration with APIs, tools, or your own code to retrieve live data, perform tasks, or trigger actions based on user input.

Overview

Tool calling connects your own code to ASI:One. When given access to defined tools, the model can choose to call them based on the conversation context. You then execute the corresponding code, return the results, and the model incorporates the output into its final reply.

It works on both /v1/chat/completions and /v1/responses. The examples on this page use /v1/chat/completions; see On the Responses API for what changes on the other endpoint.

A basic tool-calling request:

$
curl -X POST https://api.asi1.ai/v1/chat/completions \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: Bearer $ASI_ONE_API_KEY" \
>
  -d '{
>
    "model": "asi1",
>
    "messages": [
>
      {
>
        "role": "system",
>
        "content": "You are a weather assistant. When a user asks for the weather in a location, use the get_weather tool with the appropriate latitude and longitude for that location."
>
      },
>
      {
>
        "role": "user",
>
        "content": "What'\''s the current weather like in Indore right now?"
>
      }
>
    ],
>
    "tools": [
>
      {
>
        "type": "function",
>
        "function": {
>
          "name": "get_weather",
>
          "description": "Get current temperature for a given location (latitude and longitude).",
>
          "parameters": {
>
            "type": "object",
>
            "properties": {
>
              "latitude": { "type": "number" },
>
              "longitude": { "type": "number" }
>
            },
>
            "required": ["latitude", "longitude"]
>
          }
>
        }
>
      }
>
    ],
>
    "temperature": 0.7,
>
    "max_tokens": 1024
>
  }'

Example response

The model replies with the tool call rather than an answer:

1
{
2
    "id": "b26495eb13dc48ce863bf1405415c8ac",
3
    "choices": [{
4
        "finish_reason": "tool_calls",
5
        "index": 0,
6
        "logprobs": null,
7
        "message": {
8
            "content": "I'll get the current weather information for Indore, India for you.",
9
            "refusal": null,
10
            "role": "assistant",
11
            "annotations": null,
12
            "audio": null,
13
            "function_call": null,
14
            "tool_calls": [{
15
                "id": "call_13f125faf3cc422e81b10621",
16
                "function": {
17
                    "arguments": "{\"latitude\": 22.7196, \"longitude\": 75.8577}",
18
                    "name": "get_weather"
19
                },
20
                "type": "function"
21
            }],
22
            "reasoning_content": null
23
        }
24
    }],
25
    "created": 1768409382,
26
    "model": "asi1",
27
    "object": "chat.completion",
28
    "usage": {
29
        "completion_tokens": 40,
30
        "prompt_tokens": 2210,
31
        "total_tokens": 2250,
32
        "reasoning_tokens": 0
33
    }
34
}

Sample tools

The walkthrough below uses a real get_weather tool. Implement it in your own codebase:

1
import requests
2
3
def get_weather(latitude, longitude):
4
    response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m")
5
    data = response.json()
6
    return data['current']['temperature_2m']

Complete tool execution cycle

The full cycle, using the weather example. Every step below builds on this setup:

1
import os
2
import json
3
import requests
4
5
BASE_URL = "https://api.asi1.ai/v1"
6
headers = {
7
    "Authorization": f"Bearer {os.getenv('ASI_ONE_API_KEY')}",
8
    "Content-Type": "application/json",
9
}

Step 1: Initial request with tools

Send the tool definition alongside the user’s message:

1
# Define the get_weather tool
2
get_weather_tool = {
3
    "type": "function",
4
    "function": {
5
        "name": "get_weather",
6
        "description": "Get current temperature for a given location (latitude and longitude).",
7
        "parameters": {
8
            "type": "object",
9
            "properties": {
10
                "latitude": {"type": "number"},
11
                "longitude": {"type": "number"}
12
            },
13
            "required": ["latitude", "longitude"]
14
        }
15
    }
16
}
17
18
# User's question
19
initial_message = {
20
    "role": "user",
21
    "content": "What's the current weather like in Indore right now?"
22
}
23
24
# First call to model
25
payload = {
26
    "model": "asi1",
27
    "messages": [initial_message],
28
    "tools": [get_weather_tool],
29
    "temperature": 0.7,
30
    "max_tokens": 1024
31
}
32
33
first_response = requests.post(
34
    f"{BASE_URL}/chat/completions",
35
    headers=headers,
36
    json=payload
37
)

Step 2: Parse tool calls from the response

The model responds with a tool call to parse:

1
first_response.raise_for_status()
2
first_response_json = first_response.json()
3
4
tool_calls = first_response_json["choices"][0]["message"].get("tool_calls", [])
5
messages_history = [
6
    initial_message,
7
    first_response_json["choices"][0]["message"]
8
]

Step 3: Execute tools and format results

Execute the tool and format the result. get_weather is the function defined in Sample tools above:

1
for tool_call in tool_calls:
2
    function_name = tool_call["function"]["name"]
3
    arguments = json.loads(tool_call["function"]["arguments"])
4
5
    if function_name == "get_weather":
6
        latitude = arguments["latitude"]
7
        longitude = arguments["longitude"]
8
        temperature = get_weather(latitude, longitude)
9
        result = {
10
            "temperature_celsius": temperature,
11
            "location": f"lat: {latitude}, lon: {longitude}"
12
        }
13
    else:
14
        result = {"error": f"Unknown tool: {function_name}"}
15
16
    # Tool result message
17
    tool_result_message = {
18
        "role": "tool",
19
        "tool_call_id": tool_call["id"],
20
        "content": json.dumps(result)
21
    }
22
    messages_history.append(tool_result_message)

Step 4: Send results back to the model

Send the tool result back to the model:

1
# Final call to model with tool results
2
final_payload = {
3
    "model": "asi1",
4
    "messages": messages_history,
5
    "temperature": 0.7,
6
    "max_tokens": 1024
7
}
8
9
final_response = requests.post(
10
    f"{BASE_URL}/chat/completions",
11
    headers=headers,
12
    json=final_payload
13
)

Step 5: Receive the final answer

The model now answers, incorporating the tool result:

1
final_response.raise_for_status()
2
final_response_json = final_response.json()
3
4
# Final result
5
print(final_response_json["choices"][0]["message"]["content"])

Tool result handling

Here are key guidelines to ensure correct behavior and prevent common errors.

1
# Correct
2
tool_result_message = {
3
    "role": "tool",
4
    "tool_call_id": tool_call["id"],  # Use the exact ID from the tool call
5
    "content": json.dumps(result),
6
}
7
8
# Incorrect - Don't make up IDs
9
tool_result_message = {
10
    "role": "tool",
11
    "tool_call_id": "my_custom_id",  # This will cause an error
12
    "content": json.dumps(result),
13
}

1
# Correct
2
tool_result_message = {"content": json.dumps({"key": "value"})}
3
4
# Incorrect - Don't send raw objects
5
tool_result_message = {"content": {"key": "value"}}  # This will cause an error

1
try:
2
    result = execute_tool(function_name, arguments)
3
    content_to_send = json.dumps(result)
4
except Exception as e:
5
    error_content = {
6
        "error": f"Tool execution failed: {str(e)}",
7
        "status": "failed",
8
    }
9
    content_to_send = json.dumps(error_content)
10
11
tool_result_message = {
12
    "role": "tool",
13
    "tool_call_id": tool_call["id"],  # Still use the original tool call ID
14
    "content": content_to_send,
15
}
16
messages_history.append(tool_result_message)

Tool definition

Functions are specified using the tools parameter in each API request, where each tool is described as a function object.

Each function is defined using a schema that tells the model what the function does and what input arguments it requires. The schema includes the following key fields:

• name (string) : A unique, descriptive identifier for the tool (e.g., get_weather_forecast, send_email). Use underscores or camelCase formatting. Avoid spaces or special characters.

• description (string) : A detailed explanation of what the tool does and when it should be used. Clear, specific descriptions improve the model’s ability to use the function correctly.

• parameters (object) : Defines the input parameters the tool expects.

  • type (string) : Usually set to "object" to represent input parameters.

  • properties (object) : Lists each input parameter and its details:

  • type (string): The data type (e.g., string, integer, boolean, array).

  • description (string): A clear explanation of the parameter’s purpose and expected format. Example: "City and country, e.g., 'Paris, France'"

  • enum (optional): An array of allowed values, useful when inputs must be restricted. Example: "enum": ["celsius", "fahrenheit"]

  • required (array of strings) : Lists the parameter names that must be included when calling the function.

The get_weather definition used throughout this page is a minimal example of that shape. Descriptions are the part worth spending time on: the model chooses which tool to call, and what to pass it, from your prose alone.

Additional configurations

ASI:One provides several options to control how and when tools are called, as well as how strictly the model adheres to your function schemas.

Tool choice

By default, the model determines when and how many tools to use. You can control this behavior with the tool_choice parameter:

• Auto (default): The model may call zero, one, or multiple functions.

1
"tool_choice": "auto"

• Required: The model must call at least one function.

1
"tool_choice": "required"

• Forced Function: Force the model to call a specific function.

1
"tool_choice": {
2
  "type": "function",
3
  "function": { "name": "get_weather" }
4
}

• None: Prevent the model from calling any functions.

1
"tool_choice": "none"

Parallel tool calling

By default, the model may call multiple functions in a single turn. To restrict it to one at a time, send parallel_tool_calls, which both endpoints take:

1
"parallel_tool_calls": false

Strict mode

Setting strict to true makes the model follow your schema exactly rather than treating it as a strong suggestion. Enable it unless you have a reason not to.

Two things are required alongside it:

1. additionalProperties must be false on every object inside parameters.
2. Every key in properties must be listed in required.

Here is the same get_weather tool with strict mode on, plus an optional units parameter to show what that second requirement means in practice:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "get_weather",
5
    "description": "Get current temperature for a given location (latitude and longitude).",
6
    "strict": true,
7
    "parameters": {
8
      "type": "object",
9
      "properties": {
10
        "latitude": { "type": "number" },
11
        "longitude": { "type": "number" },
12
        "units": {
13
          "type": ["string", "null"],
14
          "description": "Units to report the temperature in, celsius or fahrenheit. Null for the default."
15
        }
16
      },
17
      "required": ["latitude", "longitude", "units"],
18
      "additionalProperties": false
19
    }
20
  }
21
}

Strict mode leaves no room for a parameter the model may simply omit. Widen an optional one to accept "null", list it in required like any other, and treat null as “not supplied” in your own code.

On the Responses API

Everything above uses /v1/chat/completions. Tool calling works the same way on /v1/responses, with three differences:

• Tools may use the flat shape. /v1/responses accepts OpenAI’s Responses form, where name, description and parameters sit at the top level of the tool object instead of inside a nested function object. The nested Chat Completions shape is accepted too, so an existing tool definition keeps working.

  1
  {
  2
    "type": "function",
  3
    "name": "get_weather",
  4
    "description": "Get current temperature for a given location.",
  5
    "parameters": {
  6
      "type": "object",
  7
      "properties": {
  8
        "latitude": { "type": "number" },
  9
        "longitude": { "type": "number" }
  10
      },
  11
      "required": ["latitude", "longitude"]
  12
    }
  13
  }

• Only function tools are supported. Any other tool type is rejected with a 400.

tool_choice, strict and parallel_tool_calls behave identically on both endpoints.

Next steps

1. Structured Data - Make the model’s reply conform to a JSON schema
2. Chat Completions API - How tool calls arrive when you stream the reply
3. Planner Mode - Let ASI:One plan and run multi-step work against agents and tools
4. Using ASI:One with LangChain - Bind tools with @tool instead of raw JSON schemas