Tool Definition docs

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

@@ -0,0 +1,38 @@
+---
+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
+    ...
+```
+
+## Additional Information
+
+- _**Defaults:**_ The default value for optional parameters is not sent to the language model.
+- _**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.
+- _**Annotations:**_ The annotation for each parameter is sent to the language model, thus each parameter must be annotated.
+- _**Tool Definition Schema:**_ Check out the [Tool Definition JSON schema](https://github.com/ArcadeAI/arcade-ai/blob/main/schemas/preview/tool_definition.schema.jsonc) for more details on how to define your tools.
+
+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 formatted tool definitions](home/use-tools/get-tool-definitions) documentation.