docs: clarify custom tools can execute scripts in any language with Python example

1 files changed, 58 insertions, 20 deletions

diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx
index 052468f0a..2701be650 100644
--- a/packages/web/src/content/docs/custom-tools.mdx
+++ b/packages/web/src/content/docs/custom-tools.mdx
@@ -9,7 +9,7 @@ Custom tools are functions you create that the LLM can call during conversations
 
 ## Creating a tool
 
-Tools are defined as **TypeScript** or **JavaScript** files.
+Tools are defined as **TypeScript** or **JavaScript** files. However, the tool definition can invoke scripts written in **any language** — TypeScript or JavaScript is only used for the tool definition itself.
 
 ---
 
@@ -45,6 +45,40 @@ The **filename** becomes the **tool name**. The above creates a `database` tool.
 
 ---
 
+#### Multiple tools per file
+
+You can also export multiple tools from a single file. Each export becomes **a separate tool** with the name **`<filename>_<exportname>`**:
+
+```ts title=".opencode/tool/math.ts"
+import { tool } from "@opencode-ai/plugin"
+
+export const add = tool({
+  description: "Add two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return args.a + args.b
+  },
+})
+
+export const multiply = tool({
+  description: "Multiply two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return args.a * args.b
+  },
+})
+```
+
+This creates two tools: `math_add` and `math_multiply`.
+
+---
+
 ### Arguments
 
 You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types.
@@ -74,7 +108,7 @@ export default {
 
 ---
 
-## Context
+### Context
 
 Tools receive context about the current session:
 
@@ -94,34 +128,38 @@ export default tool({
 
 ---
 
-## Multiple tools per file
+## Examples
 
-You can also export multiple tools from a single file. Each export becomes **a separate tool** with the name **`<filename>_<exportname>`**:
+### Write a tool in Python
 
-```ts title=".opencode/tool/math.ts"
-import { tool } from "@opencode-ai/plugin"
+You can write your tools in any language you want. Here's an example that adds two numbers using Python.
 
-export const add = tool({
-  description: "Add two numbers",
-  args: {
-    a: tool.schema.number().describe("First number"),
-    b: tool.schema.number().describe("Second number"),
-  },
-  async execute(args) {
-    return args.a + args.b
-  },
-})
+First, create the tool as a Python script:
 
-export const multiply = tool({
-  description: "Multiply two numbers",
+```python title=".opencode/tool/add.py"
+import sys
+
+a = int(sys.argv[1])
+b = int(sys.argv[2])
+print(a + b)
+```
+
+Then create the tool definition that invokes it:
+
+```ts title=".opencode/tool/python-add.ts" {10}
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Add two numbers using Python",
   args: {
     a: tool.schema.number().describe("First number"),
     b: tool.schema.number().describe("Second number"),
   },
   async execute(args) {
-    return args.a * args.b
+    const result = await Bun.$`python3 .opencode/tool/add.py ${args.a} ${args.b}`.text()
+    return result.trim()
   },
 })
 ```
 
-This creates two tools: `math_add` and `math_multiply`.
+Here we are using the [`Bun.$`](https://bun.com/docs/runtime/shell) utility to run the Python script.