From 6107666d047cf746988b9115b15bb3d55e7a16bf Mon Sep 17 00:00:00 2001
From: Jay V <air@live.ca>
Date: Mon, 22 Sep 2025 15:58:48 -0400
Subject: [PATCH] docs: edit tools doc

---
 .../web/src/content/docs/custom-tools.mdx     | 142 +++++++++---------
 1 file changed, 72 insertions(+), 70 deletions(-)

diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx
index 69a1783b..77b237c8 100644
--- a/packages/web/src/content/docs/custom-tools.mdx
+++ b/packages/web/src/content/docs/custom-tools.mdx
@@ -1,43 +1,69 @@
 ---
-title: Custom tools
-description: Create custom tools to extend opencode capabilities.
+title: Custom Tools
+description: Create tools the LLM can call in opencode.
 ---
 
 Custom tools are functions you create that the LLM can call during conversations. They work alongside opencode's built-in tools like `read`, `write`, and `bash`.
 
 ---
 
-## Tool structure
+## Creating a tool
 
-Tools are defined as `.ts/.js` files in the `.opencode/tool/` directory. They
-can also be defined globally in `~/.config/opencode/tool/`.
+Tools are defined as **TypeScript** or **JavaScript** files.
 
-The easiest way to create tools is using the `tool()` helper which provides type safety and validation. Use `tool.schema` (which is just [Zod](https://zod.dev)) to define argument types:
+---
 
-```ts title=".opencode/tool/database.ts"
+### Location
+
+They can defined:
+
+- Locally by placing them in the `.opencode/tool/` directory of your project.
+- Or globally, by placing them in `~/.config/opencode/tool/`.
+
+---
+
+### Structure
+
+The easiest way to create tools is using the `tool()` helper which provides type-safety and validation.
+
+```ts title=".opencode/tool/database.ts" {1}
 import { tool } from "@opencode-ai/plugin"
 
 export default tool({
   description: "Query the project database",
   args: {
-    query: tool.schema.string().describe("SQL query to execute"),
+    query: tool.schema.string().describe("SQL query to execute")
   },
   async execute(args) {
     // Your database logic here
     return `Executed query: ${args.query}`
-  },
+  }
 })
 ```
 
+The **filename** becomes the **tool name**. The above creates a `database` tool.
+
+---
+
+### Arguments
+
+You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types.
+
+```ts "tool.schema"
+args: {
+  query: tool.schema.string().describe("SQL query to execute")
+}
+```
+
 You can also import [Zod](https://zod.dev) directly and return a plain object:
 
-```ts
+```ts {6}
 import { z } from "zod"
 
 export default {
   description: "Tool description",
   args: {
-    param: z.string().describe("Parameter description"),
+    param: z.string().describe("Parameter description")
   },
   async execute(args, context) {
     // Tool implementation
@@ -46,71 +72,13 @@ export default {
 }
 ```
 
-The filename becomes the tool name. This creates a `database` tool.
-
----
-
-## Multiple tools per file
-
-You can 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
-
-Use `tool.schema` (which is just [Zod](https://zod.dev)) to define tool arguments with validation and descriptions:
-
-```ts title=".opencode/tool/calculator.ts"
-import { tool } from "@opencode-ai/plugin"
-
-export default tool({
-  description: "Perform mathematical calculations",
-  args: {
-    expression: tool.schema.string().describe("Mathematical expression to evaluate"),
-    precision: tool.schema.number().optional().describe("Decimal precision"),
-  },
-  async execute(args) {
-    // Your calculation logic here
-    return `Result: ${eval(args.expression).toFixed(args.precision || 2)}`
-  },
-})
-```
-
 ---
 
 ## Context
 
 Tools receive context about the current session:
 
-```ts title=".opencode/tool/project.ts"
+```ts title=".opencode/tool/project.ts" {8}
 import { tool } from "@opencode-ai/plugin"
 
 export default tool({
@@ -123,3 +91,37 @@ export default 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`.