Tool Definition docs

pages/home/build-tools/tool-definition.mdx

@@ -0,0 +1,49 @@
+---
+title: "Tool Definition"
+description: "Documentation for what is sent to the language model when defining a tool"
+---
+
+# Tool Definitions
+
+When defining an Arcade tool, it's important to understand which parts of the tool's definition are sent to the language model and which are not. This understanding helps in designing tools that effectively communicate their purpose and usage to the model.
+
+```python
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/gmail.compose"],
+    )  # Not sent to the model
+)
+async def write_draft_email(  # Tool name and toolkit name is sent to the model
+    context: ToolContext,  # ToolContext is never sent to the model
+    subject: Annotated[str, "Subject of the email"],  # Sent to the model
+    body: Annotated[str, "Body content of the email"],  # Sent to the model
+    recipient: Annotated[str, "Email recipient"],  # Sent to the model
+    cc: Annotated[Optional[list[str]], "CC recipients"],  # Sent to the model
+    bcc: Annotated[Optional[list[str]], "BCC recipients"],  # Sent to the model
+) -> Annotated[dict, "Email draft details"]:  # Return type not sent to the model
+    """
+    Drafts an email with the given subject and body.  # Sent to the model
+    """
+    # The body of the function is not sent to the model
+    ...
+```
+
+## Parts Sent to the Language Model
+
+1. _**Toolkit Name and Tool Name:**_ The names of the toolkit and the specific tool are sent to the language model.
+2. _**Function Docstring:**_ The docstring of the function is sent to the language model. This provides a high-level description of what the tool does.
+3. _**Parameter Names:**_ Each parameter's name is sent to the language model.
+4. _**Parameter Types:**_ The type of each parameter is sent to the language model.
+5. _**Enum Values:**_ If a parameter is an enum, each possible value for the enum is sent to the language model. This provides clarity on the valid options for that parameter.
+6. _**Parameter Annotations:**_ The annotation for each parameter is sent to the language model. Annotations often provide additional context or constraints on the parameter.
+7. _**Parameter Requirement:**_ Whether a parameter is required or optional is sent to the language model.
+
+## Parts Not Sent to the Language Model
+
+1. _**Default Values for Optional Parameters:**_ The default value assigned to an optional parameter is not sent to the language model. This means the language model does not have information on what default behavior to expect if a parameter is not provided.
+2. _**Function Body:**_ The actual implementation of the function, i.e., the function body, is not sent to the language model. This keeps the focus on the interface rather than the implementation details.
+3. _**`@tool` Decorator Details:**_ Any specifics within the `@tool` decorator, such as authentication requirements or other configurations, are not sent to the language model.
+4. _**Return Type:**_ The type of the return value is not sent to the language model. This means the language model does not have explicit information on what type of data to expect as output.
+5. _**Return Annotation:**_ Similar to the return type, the return annotation is not sent to the language model. This excludes any additional context or constraints on the return value from the language model's understanding.
+
+Understanding these distinctions helps in crafting tools that are clear and informative for the language model. If you are ever unsure about what is sent to the language model, you can always retrieve a tool's definition formatted for a specific model. For more details, refer to the [get tool definitions](home/use-tools/get-tool-definitions) documentation.