Parameter Types in Tool Use

This page provides usage examples of the JSON Schema parameters that are supported in Structured Outputs (Tools).

Note: When the strict_tools (experimental) is set to True, the outputs are guaranteed to follow the schema for the tool name, parameter name, parameter data types, and the list of required parameters.

Basic types

String

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "get_weather",
6            "description" : "Gets the weather of a given location",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                "location": {
11                    "type" : "string",
12                    "description": "The location to get weather."
13                }
14                },
15                "required": ["location"]
16            }
17            }
18    },
19]
20
21message = "What's the weather in Toronto?"

Example output:

1get_weather
2{
3  "location": "Toronto"
4}

Integer

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "add_numbers",
6            "description": "Adds two numbers",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "first_number": {
11                        "type": "integer",
12                        "description": "The first number to add.",
13                    },
14                    "second_number": {
15                        "type": "integer",
16                        "description": "The second number to add.",
17                    },
18                },
19                "required": ["first_number", "second_number"],
20            },
21        },
22    }
23]
24
25message = "What is five plus two"

Example output:

1add_numbers
2{
3  "first_number": 5,
4  "second_number": 2
5}

Float

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "add_numbers",
6            "description": "Adds two numbers",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "first_number": {
11                        "type": "number",
12                        "description": "The first number to add.",
13                    },
14                    "second_number": {
15                        "type": "number",
16                        "description": "The second number to add.",
17                    },
18                },
19                "required": ["first_number", "second_number"],
20            },
21        },
22    }
23]
24
25message = "What is 5.3 plus 2"

Example output:

1add_numbers
2{
3  "first_number": 5.3,
4  "second_number": 2
5}

Boolean

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "reserve_tickets",
6            "description": "Reserves a train ticket",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "quantity": {
11                        "type": "integer",
12                        "description": "The quantity of tickets to reserve.",
13                    },
14                    "trip_protection": {
15                        "type": "boolean",
16                        "description": "Indicates whether to add trip protection.",
17                    },
18                },
19                "required": ["quantity", "trip_protection"],
20            },
21        },
22    }
23]
24
25message = "Book me 2 tickets. I don't need trip protection."

Example output:

1reserve_tickets
2{
3  "quantity": 2,
4  "trip_protection": false
5}

Array

With specific types

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "get_weather",
6            "description" : "Gets the weather of a given location",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                "locations": {
11                    "type": "array",
12                    "items": {"type": "string"},
13                    "description": "The locations to get weather."
14                }
15                },
16                "required": ["locations"]
17            }
18            }
19    },
20]
21
22message = "What's the weather in Toronto and New York?"

Example output:

1get_weather
2{
3  "locations": [
4    "Toronto",
5    "New York"
6  ]
7}

Without specific types

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "get_weather",
6            "description" : "Gets the weather of a given location",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                "locations": {
11                    "type": "array",
12                    "description": "The locations to get weather."
13                }
14                },
15                "required": ["locations"]
16            }
17            }
18    },
19]
20
21message = "What's the weather in Toronto and New York?"

Example output:

1get_weather
2{
3  "locations": [
4    "Toronto",
5    "New York"
6  ]
7}

Lists of lists

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "maxPoints",
6            "description": "Finds the maximum number of points on a line.",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "points": {
11                        "type": "array",
12                        "description": "The list of points. Points are 2 element lists [x, y].",
13                        "items": {
14                            "type": "array",
15                            "items": {"type": "integer"},
16                            "description": "A point represented by a 2 element list [x, y].",
17                        }
18                    }
19                },
20                "required": ["points"],
21            }
22        }
23    }
24]
25
26message = "Please provide the maximum number of collinear points for this set of coordinates - [[1,1],[2,2],[3,4],[5,5]]."

Example output:

1maxPoints
2{
3  "points": [
4    [1,1],
5    [2,2],
6    [3,4],
7    [5,5]
8  ]
9}

Others

Nested objects

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "search_furniture_products",
6            "description": "Searches for furniture products given the user criteria.",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "product_type": {
11                        "type": "string",
12                        "description": "The type of the product to search for.",
13                    },
14                    "features": {
15                        "type": "object",
16                        "properties": {
17                            "material": {"type": "string"},
18                            "style": {"type": "string"},
19                        },
20                        "required": ["style"],
21                    },
22                },
23                "required": ["product_type"],
24            },
25        },
26    }
27]
28
29message = "I'm looking for a dining table made of oak in Scandinavian style."

Example output:

1search_furniture_products
2{
3  "features": {
4    "material": "oak",
5    "style": "Scandinavian"
6  },
7  "product_type": "dining table"
8}

Enums

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "fetch_contacts",
6            "description": "Fetch a contact by type",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "contact_type": {
11                        "type": "string",
12                        "description": "The type of contact to fetch.",
13                        "enum": ["customer", "supplier"]
14                    }
15                },
16                "required": ["contact_type"]
17            }
18        }
19    }
20]
21
22message = "Give me vendor contacts."

Example output:

1fetch_contacts
2{
3  "contact_type": "supplier"
4}

Const

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "get_weather",
6            "description" : "Gets the weather of a given location",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                "location": {
11                    "type": "string",
12                    "description": "The location to get weather."
13                },
14                "country": {
15                    "type": "string",
16                    "description": "The country for the weather lookup",
17                    "const": "Canada"
18                }
19                },
20                "required": ["location", "country"]
21            }
22            }
23    },
24]
25
26message = "What's the weather in Toronto and Vancouver?"

Example output:

1get_weather
2{
3  "country": "Canada",
4  "location": "Toronto"
5}
6---
7get_weather
8{
9  "country": "Canada",
10  "location": "Vancouver"
11}
12---

Pattern

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "query_product_by_sku",
6            "description": "Queries products by SKU pattern",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "sku_pattern": {
11                        "type": "string",
12                        "description": "Pattern to match SKUs",
13                        "pattern": "[A-Z]{3}[0-9]{4}"  
14                    }
15                },
16                "required": ["sku_pattern"]
17            }
18    }
19    }
20]
21
22message = "Check the stock level of this product - 7374 hgY"

Example output:

1query_product_by_sku
2{
3  "sku_pattern": "HGY7374"
4}

Format

PYTHON
1tools = [
2    {
3    "type": "function",
4    "function": {
5            "name": "book_hotel",
6            "description": "Books a hotel room for a specific check-in date",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "hotel_name": {
11                        "type": "string",
12                        "description": "Name of the hotel"
13                    },
14                    "check_in_date": {
15                        "type": "string",
16                        "description": "Check-in date for the hotel",
17                        "format": "date"
18                    }
19                },
20                "required": ["hotel_name", "check_in_date"]
21            }
22    }
23    }
24]
25
26message = "Book a room at the Grand Hotel with check-in on Dec 2 2024"

Example output:

1book_hotel
2{
3  "check_in_date": "2024-12-02",
4  "hotel_name": "Grand Hotel"
5}