Tool Calling Quick Start

1
from openai import OpenAI
2

3
client = OpenAI(
4
    base_url="https://api.runcaptain.com/v1",
5
    api_key="your_api_key",
6
    default_headers={"X-Organization-ID": "your_org_id"}
7
)
8

9
# Define your tool
10
tools = [{
11
    "type": "function",
12
    "function": {
13
        "name": "calculate",
14
        "description": "Perform arithmetic",
15
        "parameters": {
16
            "type": "object",
17
            "properties": {
18
                "operation": {"type": "string", "enum": ["add", "multiply"]},
19
                "a": {"type": "number"},
20
                "b": {"type": "number"}
21
            },
22
            "required": ["operation", "a", "b"]
23
        },
24
        "strict": True  # Required!
25
    }
26
}]
27

28
# Make request
29
response = client.chat.completions.create(
30
    model="captain-voyager-latest",
31
    messages=[{"role": "user", "content": "What is 50 times 3?"}],
32
    tools=tools
33
)
34

35
# Check if model wants to use tool
36
if response.choices[0].finish_reason == "tool_calls":
37
    import json
38
    tool_call = response.choices[0].message.tool_calls[0]
39
    args = json.loads(tool_call.function.arguments)
40

41
    # Execute tool on your side
42
    if args["operation"] == "multiply":
43
        result = args["a"] * args["b"]
44
        print(f"Result: {result}")

1
{
2
    "type": "function",           # Always "function"
3
    "function": {
4
        "name": "tool_name",      # Unique name
5
        "description": "...",     # Clear description
6
        "parameters": {...},      # JSON Schema
7
        "strict": True            # REQUIRED!
8
    }
9
}

1
tools = [{
2
    "type": "function",
3
    "function": {
4
        "name": "get_weather",
5
        "description": "Get current weather",
6
        "parameters": {
7
            "type": "object",
8
            "properties": {
9
                "city": {"type": "string"}
10
            },
11
            "required": ["city"]
12
        },
13
        "strict": True
14
    }
15
}]

1
tools = [{
2
    "type": "function",
3
    "function": {
4
        "name": "query_users",
5
        "description": "Query user database",
6
        "parameters": {
7
            "type": "object",
8
            "properties": {
9
                "user_id": {"type": "string"}
10
            },
11
            "required": ["user_id"]
12
        },
13
        "strict": True
14
    }
15
}]

1
tools = [{
2
    "type": "function",
3
    "function": {
4
        "name": "read_file",
5
        "description": "Read file contents",
6
        "parameters": {
7
            "type": "object",
8
            "properties": {
9
                "filename": {"type": "string"}
10
            },
11
            "required": ["filename"]
12
        },
13
        "strict": True
14
    }
15
}]

1
# Clear, specific descriptions
2
"description": "Calculate the sum of two numbers. Use for addition only."
3

4
# Strict parameter types
5
"parameters": {
6
    "type": "object",
7
    "properties": {
8
        "amount": {"type": "number"},
9
        "currency": {"type": "string", "enum": ["USD", "EUR"]}
10
    },
11
    "required": ["amount", "currency"]
12
}
13

14
# Validate inputs before execution
15
def execute_tool(name, args):
16
    if name not in ALLOWED_TOOLS:
17
        raise ValueError("Tool not allowed")
18
    return ALLOWED_TOOLS[name](**args)

1
# Vague description
2
"description": "Does stuff"
3

4
# Missing types
5
"parameters": {
6
    "type": "object",
7
    "properties": {
8
        "data": {}  # What type?
9
    }
10
}
11

12
# No input validation
13
def execute_tool(name, args):
14
    return eval(f"{name}(**{args})")  # Dangerous!

1
# Make description more explicit
2
"description": "ALWAYS use this tool for math. Never calculate manually."
3

4
# Strengthen system prompt
5
messages = [
6
    {
7
        "role": "system",
8
        "content": "You MUST use provided tools. Don't do calculations yourself."
9
    },
10
    {"role": "user", "content": "What is 5 + 3?"}
11
]

1
# Check for missing args
2
args = json.loads(tool_call.function.arguments)
3
if not args.get("required_param"):
4
    # Provide default or skip
5
    args["required_param"] = "default"

1
# Wrap in try-catch
2
try:
3
    result = execute_tool(name, args)
4
except Exception as e:
5
    result = {"error": str(e)}