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 Python 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 Python type as a definition for these parameters. This includes basic types like integers, floats, and strings, as well as more complex types such as lists, dictionaries, and dataclasses.

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 Python types, defaults, and enums.

Example - JSON Schema Type Conversion


JSON Schema typePython type
stringstr
number (float type)float
number (integer type)int
booleanbool
objectDict
object (with specific types)Dict[str, int]
arrayList
array (with specific types)List[str]
array (nested with specific types)List[List[str]]
n/aCustom Python classes such as a dataclass (see examples below)

Example – Simple types

PYTHON
1tools = [
2    {
3        "name": "query_daily_sales_report",
4        "description": "Connects to a database to retrieve overall sales volumes and sales information for a given day.",
5        "parameter_definitions": {
6            "day": {
7                "description": "Retrieves sales data for this day, formatted as YYYY-MM-DD.",
8                "type": "str", 
9                "required": True
10            }
11        }
12    }
13]
14
15message = "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?"
16
17response = co.chat(
18    message=message,
19    tools=tools
20)

Example – Arrays

With specific element types

PYTHON
1tools = [
2   {
3       "name": "query_daily_sales_report",
4       "description": "Connects to a database to retrieve overall sales volumes and sales information for numerous days.",
5       "parameter_definitions": {
6           "days": {
7               "description": "Retrieves sales data for these days, formatted as YYYY-MM-DD.",
8               "type": "List[str]", # or "List[float]", "List[List[str]]" etc
9               "required": True
10           }
11       }
12   },
13 }
14]

Without specific element types

PYTHON
1tools = [
2    {
3        "name": "query_daily_sales_report",
4        "description": "Connects to a database to retrieve overall sales volumes and sales information for numerous days.",
5        "parameter_definitions": {
6            "days": {
7                "description": "Retrieves sales data for these days, formatted as YYYY-MM-DD.",
8                "type": "List",
9                "required": True
10            }
11        }
12    }
13]

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        "name": "fetch_contacts",
4        "description": "Fetch a contact by type",
5        "parameter_definitions": {
6            "contact_type": {
7                "description": "The type of contact to fetch. Possible enum values: customer, supplier.",
8                "type": "str",
9                "required": True
10            }
11        }
12    }
13]

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        "name": "fetch_contacts",
4        "description": "Fetch a contact by type",
5        "parameter_definitions": {
6            "contact_type": {
7                "description": "The type of contact to fetch. The default value is: customer.",
8                "type": "str",
9                "required": True
10            }
11        }
12    }
13]

Example – Dictionaries

We recommend using individual parameters whenever possible. However, when that’s not possible, to make sure a tool is called with a specific array or dictionary structure you can specify the keys in the parameter’s description. For example:

PYTHON
1tools = [
2    {
3        "name": "plot_daily_sales_volume",
4        "description": "Produce a graph from daily sales volume data.",
5        "parameter_definitions": {
6            "sales_data": {
7                "description": "Produces a graph from sales volume data. The key is the day,formatted as YYYY-MM-DD, and the value is the number of sales",
8                "type": "Dict[str, int]",
9                "required": True
10            }
11        }
12    }
13]

Example - Python objects (including dataclass)

It’s possible to call a tool that accepts custom Python objects, for example a data class.

PYTHON
1from dataclasses import dataclass
2
3
4@dataclass
5class InventoryItem:
6    name: str
7    category: str  # one of ["fruit", "stationery", "diary"]
8    is_food: bool
9
10
11tools = [
12    {
13        "name": "find_stock",
14        "description": "Find how many items are in stock.",
15        "parameter_definitions": {
16            "item": {
17                "description": """An InventoryItem object that represents an item. The definition of InventoryItem looks like the following:
18@dataclass
19class InventoryItem:
20    name: str
21    category: str  # one of ["fruit", "stationery", "diary"]
22    is_food: bool
23""",
24                "type": "InventoryItem",
25                "required": True
26            }
27        }
28    }
29]