Parameter types for tool use (function calling)

Structured Outputs (Tools)

The Structured Outputs feature guarantees that an LLM’s response will strictly follow a schema specified by the user.

While this feature is supported in two scenarios (JSON and tools), this page will focus on the tools scenario.

Usage

When you use the Chat API with tools, setting the strict_tools parameter to True will guarantee that every generated tool call follows the specified tool schema.

Concretely, this means:

  • No hallucinated tool names
  • No hallucinated tool parameters
  • Every required parameter is included in the tool call
  • All parameters produce the requested data types

With strict_tools enabled, the API will ensure that the tool names and tool parameters are generated according to the tool definitions. This eliminates tool name and parameter hallucinations, ensures that each parameter matches the specified data type, and that all required parameters are included in the model response.

Additionally, this results in faster development. You don’t need to spend a lot of time prompt engineering the model to avoid hallucinations.

When the strict_tools parameter is set to True, you can define a maximum of 200 fields across all tools being passed to an API call.

1response = co.chat(model="command-r-plus-08-2024",
2    messages=[{"role": "user", "content": "What's the weather in Toronto?"}],
3    tools=tools,
4    strict_tools=True
5)

Important notes

When using strict_tools, the following notes apply:

  • This parameter is only supported in Chat API V2 via the strict_tools parameter (not API V1).
  • You must specify at least one required parameter. Tools with only optional parameters are not supported in this mode.
  • You can define a maximum of 200 fields across all tools in a single Chat API call.

Supported parameter types

Structured Outputs supports a subset of the JSON Schema specification. Refer to the Structured Outputs documentation for the list of supported and unsupported parameters.

Usage examples

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

The examples on this page each provide a tool schema and a message (the user message). To get an output, pass those values to a Chat endpoint call, as shown in the helper code below.

PYTHON
1# ! pip install -U cohere
2import cohere
3
4co = cohere.ClientV2(
5    "COHERE_API_KEY"
6)  # Get your free API key here: https://dashboard.cohere.com/api-keys
PYTHON
1response = co.chat(
2    # The model name. Example: command-r-plus-08-2024
3    model="MODEL_NAME",
4    # The user message. Optional - you can first add a `system_message` role
5    messages=[
6        {
7            "role": "user",
8            "content": message,
9        }
10    ],
11    # The tool schema that you define
12    tools=tools,
13    # This guarantees that the output will adhere to the schema
14    strict_tools=True,
15    # Typically, you'll need a low temperature for more deterministic outputs
16    temperature=0,
17)
18
19for tc in response.message.tool_calls:
20    print(f"{tc.function.name} | Parameters: {tc.function.arguments}")

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 the weather, example: San Francisco.",
13                    }
14                },
15                "required": ["location"],
16            },
17        },
18    },
19]
20
21message = "What's the weather in Toronto?"

Example response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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 response:

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