update tool use pages

cohere-ai · Feb 7, 2025 · 91d1d48 · 91d1d48
1 parent c65e921
commit 91d1d48
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 71 deletions.
diff --git a/fern/pages/v2/tool-use/tool-use-citations.mdx b/fern/pages/v2/tool-use/tool-use-citations.mdx
@@ -73,7 +73,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "the location to get weather. Provide just the city name without the country name.",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],

diff --git a/fern/pages/v2/tool-use/tool-use-overview.mdx b/fern/pages/v2/tool-use/tool-use-overview.mdx
@@ -14,9 +14,9 @@ updatedAt: "Tue Jun 18 2024 07:20:15 GMT+0000 (Coordinated Universal Time)"
 
 ## Overview
 
-Tool use is a technique which allows developers to connect Cohere’s Command R family of models to external tools like search engines, APIs, functions, databases, etc.
+Tool use is a technique which allows developers to connect Cohere’s Command family models to external tools like search engines, APIs, functions, databases, etc.
 
-This opens up a richer set of behaviors by leveraging data stored in tools, taking actions through APIs, interacting with a vector database, querying a search engine, etc., and is particularly valuable for enterprise developers, since a lot of enterprise data lives in external sources.
+This opens up a richer set of behaviors by leveraging tools to access external data sources, taking actions through APIs, interacting with a vector database, querying a search engine, etc., and is particularly valuable for enterprise developers, since a lot of enterprise data lives in external sources.
 
 The Chat endpoint comes with built-in tool use capabilities such as function calling, multi-step reasoning, and citation generation.
 
@@ -76,17 +76,21 @@ functions_map = {"get_weather": get_weather}
 
 ### Defining the tool schema
 
-We also need to define the tool schemas in a format that can be passed to the Chat endpoint. The schema follows the [JSON Schema specification](https://json-schema.org/) and must contain the following fields: 
+We also need to define the tool schemas in a format that can be passed to the Chat endpoint. The schema follows the [JSON Schema specification](https://json-schema.org/understanding-json-schema) and must contain the following fields: 
 - `name`: the name of the tool.
 - `description`: a description of what the tool is and what it is used for.
 - `parameters`: a list of parameters that the tool accepts. For each parameter, we need to define the following fields:
   - `type`: the type of the parameter.
   - `properties`: the name of the parameter and the following fields:
     - `type`: the type of the parameter.
     - `description`: a description of what the parameter is and what it is used for.
-  - `required`: a list of required parameters from the `properties` field.
+  - `required`: a list of required properties by name, which appear as keys in the `properties` object
 
-This schema informs the LLM about what the tool does, and the LLM decides whether to use a particular tool based on the information that it contains. Therefore, the more descriptive and clear the schema, the more likely the LLM will make the right tool call decisions. In a typical development cycle, some fields such as `name`, `description`, and `properties` will likely require a few rounds of iterations in order to get the best results (a similar idea to prompt engineering).
+This schema informs the LLM about what the tool does, and the LLM decides whether to use a particular tool based on the information that it contains.
+
+Therefore, the more descriptive and clear the schema, the more likely the LLM will make the right tool call decisions.
+
+In a typical development cycle, some fields such as `name`, `description`, and `properties` will likely require a few rounds of iterations in order to get the best results (a similar approach to prompt engineering).
 
 ```python PYTHON
 tools = [
@@ -100,7 +104,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "the location to get weather, example: San Fransisco, CA",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],
@@ -110,6 +114,8 @@ tools = [
 ]
 ```
 
+<Note>The endpoint supports a subset of the JSON Schema specification. Refer to the [Structured Outputs documentation](https://docs.cohere.com/docs/structured-outputs#parameter-types-support) for the list of supported and unsupported parameters.</Note>
+
 ## Tool use workflow
 
 We can think of a tool use system as consisting of four components:
@@ -158,11 +164,11 @@ messages = [
 
 Next, we call the Chat endpoint to generate the list of tool calls. This is done by passing the parameters `model`, `messages`, and `tools` to the Chat endpoint.
 
-The endpoint will send back a list of tool calls to be made if the model determines that tools are required. If it does, it will return two types of messages:
+The endpoint will send back a list of tool calls to be made if the model determines that tools are required. If it does, it will return two types of information:
 - `tool_plan`: its reflection on the next steps it should take, given the user query.
-- `tool_calls`: a list of tool calls to be made (if any), together with the tool call IDs.
+- `tool_calls`: a list of tool calls to be made (if any), together with auto-generated tool call IDs.
 
-We then append this information to the `messages` list with the `role` set to `assistant`.
+We then append these to the `messages` list with the `role` set to `assistant`.
 
 ```python PYTHON
 response = co.chat(
@@ -197,12 +203,25 @@ I will search for the weather in Toronto.
 ]
 ```
 
+<AccordionGroup>
+<Accordion title='Directly responding'>
+The model can decide to *not* make any tool call, and instead, respond to a user message directly. This is described [here](https://docs.cohere.com/docs/tool-use-usage-patterns#directly-answering).
+</Accordion>
+<Accordion title='Parallel tool calling'>
+The model can determine that more than one tool call is required. This can be calling the same tool multiple times or different tools for any number of calls. This is described [here](https://docs.cohere.com/docs/tool-use-usage-patterns#parallel-tool-calling).
+</Accordion>
+</AccordionGroup>
+
 ### Step 3: Get tool results
 During this step, we perform the function calling. We call the necessary tools based on the tool call payloads given by the endpoint.
 
-For each tool call, we append the tool results to the `tool_content` list with `type` set to `document` and `document` set to the tool results (in JSON string format).
-
-We then append this information to the `messages` list with the `role` set to `tool`, together with the tool call IDs that were generated in the previous step.
+For each tool call, we append the `messages` list with:
+- the `tool_call_id` generated in the previous step.
+- the `content` of each tool result with the following fields:
+    - `type` which is `document`
+    - `document` containing
+        - `data`: which stores the contents of the tool result.
+        - `id` (optional): you can provide each document with a unique ID for use in citations, otherwise auto-generated
 
 ```python PYTHON
 import json
@@ -214,13 +233,28 @@ if response.message.tool_calls:
         )
         tool_content = []
         for data in tool_result:
-            tool_content.append({"type": "document", "document": {"data": json.dumps(data)}})
-            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
+            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
+            tool_content.append(
+                {
+                    "type": "document",
+                    "document": {
+                        "data": json.dumps(data)
+                    }
+                }
+            )
         messages.append(
-            {"role": "tool", "tool_call_id": tc.id, "content": tool_content}
+            {
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "content": tool_content
+            }
         )
 ```
 
+<Accordion title='Multi-step tool use (agents)'>
+The Chat endpoint supports multi-step tool use, allowing the model to perform agentic tasks that require sequential reasoning. This means that steps 2 and 3 will run multiple times in loop. This is described [here](https://docs.cohere.com/docs/tool-use-usage-patterns#multi-step-tool-use).
+</Accordion>
+
 ### Step 4: Generate response and citations
 By this time, the tool call has already been executed, and the result has been returned to the LLM.
 
@@ -256,20 +290,18 @@ print(response.message.citations)
 ```
 
 
-## State management
-This section gives a more detailed look at how the state is managed via the `messages` list.
+### State management
+This section provides a more detailed look at how the state is managed via the `messages` list as described in the [tool use workflow](#tool-use-workflow) above.
 
-As described in the [tool use workflow](#tool-use-workflow) section above, at each step of the workflow, the endpoint requires that we append specific types of information to the `messages` list. This is to ensure that the model has the necessary context to generate its response at a given point.
+At each step of the workflow, the endpoint requires that we append specific types of information to the `messages` list. This is to ensure that the model has the necessary context to generate its response at a given point.
 
 In summary, each single turn of a conversation that involves tool calling consists of:
 1. a `user` message containing the user message (`content`)
 2. an `assistant` message, containing the tool calling information (`tool_plan` and `tool_calls`)
 3. a `tool` message, containing the tool results (`tool_call_id` and `content`)
 4. a final `assistant` message, containing the response to the user (`content`)
 
-These correspond to the four steps described in the [tool use workflow](#tool-use-workflow) section above.
-
-The following is the list of messages from the example in the [tool use workflow](#tool-use-workflow) section.
+These correspond to the four steps described above. The list of `messages` is shown below.
 
 ```python PYTHON
 for message in messages:
@@ -308,7 +340,7 @@ for message in messages:
 }
 ```
 
-The sequence of messages is represented in the diagram below.
+The sequence of `messages` is represented in the diagram below.
 
 ```mermaid
 %%{init: {'htmlLabels': true}}%%
@@ -328,5 +360,5 @@ flowchart TD
 ```
 
 
-Note that this sequence of messages represents a basic usage pattern in tool use. The next page [[TODO - add link]] will describe how this will be adapted for other scenarios.
+Note that this sequence represents a basic usage pattern in tool use. The next page [[TODO - add link]] will describe how this is adapted for other scenarios.
 
diff --git a/fern/pages/v2/tool-use/tool-use-parameter-types.mdx b/fern/pages/v2/tool-use/tool-use-parameter-types.mdx
@@ -129,7 +129,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "The location to get weather.",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],

diff --git a/fern/pages/v2/tool-use/tool-use-streaming.mdx b/fern/pages/v2/tool-use/tool-use-streaming.mdx
@@ -278,7 +278,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "the location to get weather. Provide just the city name without the country name.",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],
@@ -321,8 +321,8 @@ if response.message.tool_calls:
         )
         tool_content = []
         for data in tool_result:
+            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
             tool_content.append({"type": "document", "document": {"data": json.dumps(data)}})
-            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
         messages.append(
             {"role": "tool", "tool_call_id": tc.id, "content": tool_content}
         )
@@ -331,7 +331,22 @@ if response.message.tool_calls:
 ```mdx wordWrap
 I will use the get_weather tool to find the weather in Madrid and Brasilia. 
 
-[ToolCallV2(id='get_weather_15c2p6g19s8f', type='function', function=ToolCallV2Function(name='get_weather', arguments='{"location":"Madrid"}')), ToolCallV2(id='get_weather_n01pkywy0p2w', type='function', function=ToolCallV2Function(name='get_weather', arguments='{"location":"Brasilia"}'))]
+[
+    ToolCallV2(
+        id="get_weather_15c2p6g19s8f",
+        type="function",
+        function=ToolCallV2Function(
+            name="get_weather", arguments='{"location":"Madrid"}'
+        ),
+    ),
+    ToolCallV2(
+        id="get_weather_n01pkywy0p2w",
+        type="function",
+        function=ToolCallV2Function(
+            name="get_weather", arguments='{"location":"Brasilia"}'
+        ),
+    ),
+]
 ```
 
 Once the tool results have been received, we can now stream the response using the `chat_stream` endpoint.

diff --git a/fern/pages/v2/tool-use/tool-use-tool-definition.mdx b/fern/pages/v2/tool-use/tool-use-tool-definition.mdx
diff --git a/fern/pages/v2/tool-use/tool-use-usage-patterns.mdx b/fern/pages/v2/tool-use/tool-use-usage-patterns.mdx
@@ -63,7 +63,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "the location to get weather, example: San Fransisco, CA",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],
@@ -132,8 +132,8 @@ if response.message.tool_calls:
         )
         tool_content = []
         for data in tool_result:
+            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
             tool_content.append({"type": "document", "document": {"data": json.dumps(data)}})
-            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
         messages.append(
             {"role": "tool", "tool_call_id": tc.id, "content": tool_content}
         )
@@ -257,7 +257,7 @@ tools = [
                 "properties": {
                     "location": {
                         "type": "string",
-                        "description": "the location to get weather. Provide just the city name without the country name.",
+                        "description": "the location to get the weather, example: San Francisco.",
                     }
                 },
                 "required": ["location"],
@@ -330,13 +330,13 @@ while response.message.tool_calls:
         tool_content = []
         print(tool_result)
         for data in tool_result:
+            # Optional: the "document" object can take an "id" field for use in citations, otherwise auto-generated
             tool_content.append(
                 {
                     "type": "document",
                     "document": {"data": json.dumps(data)},
                 }
             )
-            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
         messages.append(
             {
                 "role": "tool",