docs(custom-tools): improve docs for creating custom tools

Author: collindutter

docs/griptape-framework/tools/custom-tools/index.md

@@ -5,9 +5,9 @@ Building your own tools is easy with Griptape!
 Tools are nothing more than Python classes that inherit from [BaseTool](../../../reference/griptape/tools/base_tool.md).
 Each method in the class is decorated with an [activity](../../../reference/griptape/utils/decorators.md#griptape.utils.decorators.activity) decorator which informs the LLM how and when it should use that Tool Activity.
 
-## Random Number Generator Tool
+## Random Tool
 
-Here is a simple random number generator Tool:
+Here is a simple Tool for performing various operations with the `random` module.
 
 === "Code"
 
@@ -21,14 +21,52 @@ Here is a simple random number generator Tool:
     --8<-- "docs/griptape-framework/tools/custom-tools/logs/index_2.txt"
     ```
 
-Check out other [Griptape Tools](https://github.com/griptape-ai/griptape/tree/main/griptape/tools) to learn more about tool implementation details.
+### Tool Activities
+
+Activities are actions an LLM can perform with a various Tool. They pair a natural language description with some code to execute. Some examples:
+
+- "Can be used to create a random number" -> `generate_rand_num`
+- "Can be used to select a random item from a list" -> `select_rand_item`
+
+Technically, each Activity is a method in the tool class that's decorated with the [activity](../../../reference/griptape/utils/decorators.md#griptape.utils.decorators.activity) decorator.
+
+Griptape will convert the Tool and its Activities into the appropriate format for the LLM to use. You can see the schema for a particular Activity by calling [to_json_schema](../../../reference/griptape/mixins/activity_mixin.md#griptape.mixins.activity_mixin.ActivityMixin.to_activity_json_schema).
+
+```python
+--8<-- "docs/griptape-framework/tools/custom-tools/src/to_json_schema.py"
+```
+
+Each Activity takes a `config` keyword argument that contains the configuration for the Activity. The configuration can contain:
+
+- `description` (str): A plain text description of the Activity. Ensure that the description is clear and concise as it will help inform the LLM of when to pick this Activity.
+- `schema` (optional): An optional instance of `Schema` that defines the input values to the Activity. This field should be omitted if the Activity does not accept any input values.
+
+### Activity Methods
+
+Activity decorated methods should return an [Artifact](../../data/artifacts.md), though Griptape will automatically convert any other return type to an [InfoArtifact](../../data/artifacts.md#info).
+
+If an Activity's config declares a `schema`, the method should declare parameters using one of the following styles:
+
+- Standard python keyword arguments. See `generate_random_number`.
+- `values` (dict): A dictionary of the input values to the Activity. See `select_random_item`.
+- `params` (dict): A dictionary that will contain a single key, `values`. See `sample_list`. Other keys may be added in the future, though generally, you should prefer using one of the other styles.
+
+!!! warning
+
+    Do not name any schema fields as `values` or `params`. They are reserved for the Activity method signature.
 
 ## Tool Dependencies
 
 Each Tool can also have its own dependencies. You can specify them in a `requirements.txt` file in the tool directory and Griptape will install them during Tool execution.
 To start, create a directory for your Tool inside your project. The directory must have the following structure:
 
-- `tool.py` file with a tool Python class.
-- `requirements.txt` file with tool Python dependencies.
+```
+griptape/tools/calculator/
+├── __init__.py
+├── requirements.txt # file with tool Python dependencies
+└── tool.py # file with tool Python class
+```
 
 That's it! Import and use your Tool in your project as you would with any other Griptape Tool.
+
+Check out other [Griptape Tools](https://github.com/griptape-ai/griptape/tree/main/griptape/tools) to learn more about tool implementation details.

docs/griptape-framework/tools/custom-tools/src/index_1.py

@@ -3,26 +3,102 @@
 from schema import Literal, Optional, Schema
 
 from griptape.artifacts import TextArtifact
+from griptape.artifacts.list_artifact import ListArtifact
 from griptape.structures import Agent
 from griptape.tools import BaseTool
 from griptape.utils.decorators import activity
 
 
-class RandomNumberGenerator(BaseTool):
+class RandomTool(BaseTool):
     @activity(
         config={
             "description": "Can be used to generate random numbers",
+        }
+    )
+    def generate_rand_num(self) -> TextArtifact:
+        """Generate a random number between 0 and 1.
+
+        Returns:
+            TextArtifact: The random number as a Text Artifact.
+        """
+        return TextArtifact(random.random())
+
+    @activity(
+        config={
+            "description": "Can be used to generate random numbers",
+            "schema": Schema(
+                {
+                    Literal("start", description="The start of the rand range, inclusive."): int,
+                    Literal("stop", description="The start of the rand range, exclusive."): int,
+                }
+            ),
+        }
+    )
+    def generate_rand_range(self, start: int, stop: int) -> TextArtifact:
+        """Generate a random number between start and stop.
+
+        Args:
+            start (int): The starting number.
+            stop (int): The ending number.
+
+        Returns:
+            TextArtifact: The random number as a Text Artifact.
+        """
+        return TextArtifact(random.randrange(start, stop))
+
+    @activity(
+        config={
+            "description": "Can be used to select a random item from a list",
             "schema": Schema(
-                {Optional(Literal("decimals", description="Number of decimals to round the random number to")): int}
+                {
+                    "items": [str],
+                }
             ),
         }
     )
-    def generate(self, params: dict) -> TextArtifact:
-        return TextArtifact(str(round(random.random(), params["values"].get("decimals"))))
+    def select_rand_item(self, *, values: dict) -> TextArtifact:
+        """Select a random item from a list.
+
+        Args:
+            values (dict): The values declared by the schema.
+
+        Returns:
+            TextArtifact: The selected item as a Text Artifact.
+        """
+        items = values["items"]
+
+        return TextArtifact(random.choice(items))
+
+    @activity(
+        config={
+            "description": "Can be used to sample a list",
+            "schema": Schema(
+                {
+                    "items": [str],
+                    Optional("k"): int,
+                }
+            ),
+        }
+    )
+    def sample_list(self, *, params: dict) -> ListArtifact[TextArtifact]:
+        """Shuffle a list.
+
+        Args:
+            params (dict): A dictionary containing a key, `values`, which contains the values declared by the schema.
+
+        Returns:
+            TextArtifact: The sampled list as a List Artifact of Text Artifacts.
+        """
+        values = params["values"]
+
+        items = values["items"]
+        k = values.get("k", 5)
+
+        sampled = random.sample(items, k)
 
+        return ListArtifact([TextArtifact(item) for item in sampled])
 
-rng_tool = RandomNumberGenerator()
 
-agent = Agent(tools=[rng_tool])
+agent = Agent(tools=[RandomTool()])
 
-agent.run("generate a random number rounded to 5 decimal places")
+agent.run("Generate a number between 5 and 10, then generate that many animals, sample 3, then randomly select one.")

docs/griptape-framework/tools/custom-tools/src/index_2.py

@@ -0,0 +1,7 @@
+from rich.pretty import pprint
+
+from griptape.tools import CalculatorTool
+
+tool = CalculatorTool()
+
+pprint(tool.to_activity_json_schema(tool.calculate, "Calculate Schema"))

docs/griptape-framework/tools/custom-tools/src/to_json_schema.py

@@ -8,32 +8,9 @@ Many of our [Prompt Drivers](../drivers/prompt-drivers.md) leverage the native f
 
 You can switch between these strategies by setting `use_native_tools` to `True` (LLM-native tool calling) or `False` (Griptape tool calling) on your [Prompt Driver](../drivers/prompt-drivers.md).
 
-## Griptape Tools
+## Custom Tools
 
-Griptape tools are special Python classes that LLMs can use to accomplish specific goals. A tool consists of multiple "activities," each represented by a function decorated with `@activity`. This decorator provides context to the LLM through descriptions and defines the input schema that the LLM must follow.
-
-When a function is decorated with `@activity`, the decorator injects keyword arguments into the function according to the schema. Additionally, Griptape provides two special keyword arguments:
-
-- `params: dict`
-- `values: dict`
-
-!!! info
-
-    If your schema defines any parameters named `params` or `values`, they will be overwritten by the Griptape-provided arguments.
-
-Here is an example of a custom tool for generating a random number:
-
-=== "Code"
-
-    ```python
-    --8<-- "docs/griptape-framework/tools/src/index_1.py"
-    ```
-
-=== "Logs"
-
-    ```text
-    --8<-- "docs/griptape-framework/tools/logs/index_1.txt"
-    ```
+See [Custom Tools](./custom-tools/index.md) for more information on building your own tools.
 
 ## Tool Output and Task Memory