Tool Calling
What is Tool Calling
Tool Calling allows models to recognize when they need to use external tools or functions and generate outputs that conform to the tool schema. Through function calling, models can interact with external systems, APIs, databases, and more.
How It Works
┌─────────────────────────────────────────────────────────────────┐
│ Tool Calling Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User Request ──┐ │
│ ▼ │
│ ┌──────────────┐ │
│ │ LLM │ │
│ │ Identifies Tool Need │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Return Tool │ ← {name: "get_weather", args: {city: "Beijing"}} │
│ │ Call │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Execute │ ← Call weather API │
│ │ External Fn │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Return Result│ ← "Beijing is sunny, 25°C" │
│ │ to LLM │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Final Response│ │
│ │ to User │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘Defining Tools
Tool Schema Example
json
{
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather information for a specified city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, e.g., Beijing, Shanghai"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit, default is celsius"
}
},
"required": ["city"]
}
}
}
]
}Complete Example
Python Example
python
from openai import OpenAI
client = OpenAI(
base_url="https://ai-tokenhub.com/v1",
api_key="your_api_key"
)
# Define tools
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather information for a specified city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
# Send request
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "user", "content": "What's the weather in Beijing?"}
],
tools=tools,
tool_choice="auto"
)
# Handle tool calls
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
for call in tool_calls:
function_name = call.function.name
arguments = json.loads(call.function.arguments)
print(f"Calling function: {function_name}")
print(f"Arguments: {arguments}")
# Execute function and get result
if function_name == "get_weather":
result = get_weather(arguments["city"])
# Return result to model
result_response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "user", "content": "What's the weather in Beijing?"},
{"role": "assistant", "content": None, "tool_calls": tool_calls},
{
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result)
}
]
)
print(result_response.choices[0].message.content)Common Tool Scenarios
1. Weather Query
python
def get_weather(city: str, unit: str = "celsius"):
"""Get weather information"""
return {
"city": city,
"weather": "Sunny",
"temperature": 25,
"unit": unit
}2. Web Search
python
def web_search(query: str, limit: int = 5):
"""Web search"""
results = search_api(query, limit)
return {
"query": query,
"results": results
}3. Database Query
python
def query_database(sql: str):
"""Execute SQL query"""
result = db.execute(sql)
return {
"columns": result.columns,
"rows": result.data
}4. Send Email
python
def send_email(to: str, subject: str, body: str):
"""Send email"""
mail.send(to=to, subject=subject, body=body)
return {"status": "sent", "message_id": "xxx"}Tool Calling Parameters
tool_choice Parameter
| Value | Description |
|---|---|
auto | Model automatically decides whether to call a tool |
none | Disable tool calling, generate text directly |
{"type": "function", "function": {"name": "get_weather"}} | Force call to specified tool |
parallel_tool_calls Parameter
Control whether parallel calls to multiple tools are allowed:
python
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Check weather in Beijing and Shanghai"}],
tools=tools,
parallel_tool_calls=True
)Best Practices
1. Clear Tool Descriptions
json
{
"name": "calculate",
"description": "Python calculator for mathematical operations including addition, subtraction, multiplication, division, exponents, square roots, etc. Input should be standard mathematical expressions like '2+2', 'sqrt(16)', '10**2'"
}2. Strict Parameter Validation
json
{
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Date format: YYYY-MM-DD"
}
}
}
}3. Error Handling
python
try:
result = execute_tool(function_name, arguments)
except ToolExecutionError as e:
return {"error": str(e), "fallback": "Unable to execute this operation, please try again later"}FAQ
Q: Model doesn't call tools?
Possible reasons:
- Prompt not clear enough
- Tool description not clear
- Set to
tool_choice="none"
Q: How to force tool usage?
python
tool_choice = {"type": "function", "function": {"name": "get_weather"}}Q: What to do if tool call times out?
Set timeout mechanism:
python
import signal
def timeout_handler(signum, frame):
raise TimeoutError("Tool execution timeout")
signal.signal(signal.SIGALRM, timeout_handler)
signal.alarm(30) # 30 second timeout
try:
result = execute_tool(...)
finally:
signal.alarm(0)