Parameter Types in Tool Use

Cohere’s tool use feature is available in the chat endpoint via the API and all of our SDKs (Python, Typescript, Java, Go). The functionality relies on JSON Schema type notation to define parameters. Parameters are the inputs that a tool or function needs to operate. With this approach there is flexibility to use any JSON Schema type as a definition for these parameters. This includes basic types like integers, numbers, and strings, as well as more complex types such as arrays and objects.

Additionally, the default value for optional parameters can be provided, which will be used if no value is specified when the function is called. It is also possible to define enumerations (enums) to specify a set of valid values for a parameter, restricting the input to a predefined list of options.

Below are some examples that illustrate how to define parameters using JSON Schema types, defaults, and enums.

Example – Simple types

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "query_daily_sales_report",
6            "description": "Connects to a database to retrieve overall sales volumes and sales information for a given day.",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "day": {
11                        "type": "string",
12                        "description": "Retrieves sales data for this day, formatted as YYYY-MM-DD."
13                    }
14                },
15                "required": ["day"]
16            }
17        }
18    }
19]
20
21message = "Can you provide a sales summary for 29th September 2023, and also give me some details about the products in the 'Electronics' category, for example their prices and stock levels?"
22
23res = co.chat(model="command-r-plus-08-2024",
24              messages=[{"role": "user", "content": message}],
25              tools=tools)

Example – Arrays

With specific element types

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "query_daily_sales_report",
6            "description": "Connects to a database to retrieve overall sales volumes and sales information for numerous days.",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "days": {
11                        "type": "array",
12                        "items": {"type": "string"},
13                        "description": "Retrieves sales data formatted as YYYY-MM-DD."
14                    }
15                },
16                "required": ["days"]
17            }
18        }
19    }
20]

Without specific element types

PYTHON
1tools = [
2    {
3        "type": "function",
4        "function": {
5            "name": "query_daily_sales_report",
6            "description": "Connects to a database to retrieve overall sales volumes and sales information for numerous days.",
7            "parameters": {
8                "type": "object",
9                "properties": {
10                    "days": {
11                        "type": "array",
12                        "description": "Retrieves sales data for these days, formatted as YYYY-MM-DD."
13                    }
14                },
15                "required": ["days"]
16            }
17        }
18    }
19]

Example – Enumerated values (enums)

To make sure a tool only accepts certain values you can list those values in the parameter’s description. For example, you can say “Possible enum values: customer, supplier.”

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. Possible enum values: customer, supplier.",
13                    }
14                },
15                "required": ["contact_type"]
16            }
17        }
18    }
19]

Example - Defaults

To ensure a tool is called with a default value it’s recommended to specify the default on the tool’s implementation and use required: False whenever possible. When this is not possible you can specify the default in the parameter’s description (with required: True). For example:

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. The default value is: supplier.",
13                    }
14                },
15                "required": ["contact_type"]
16            }
17        }
18    }
19]