docs: edit tools doc

1 files changed, 61 insertions, 59 deletions

diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx
index 69a1783b7..77b237c8b 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:
+---
+
+### Location
+
+They can defined:
 
-```ts title=".opencode/tool/database.ts"
+- 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,13 +72,31 @@ export default {
 }
 ```
 
-The filename becomes the tool name. This creates a `database` tool.
+---
+
+## Context
+
+Tools receive context about the current session:
+
+```ts title=".opencode/tool/project.ts" {8}
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Get project information",
+  args: {},
+  async execute(args, context) {
+    // Access context information
+    const { agent, sessionID, messageID } = context
+    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}`
+  },
+})
+```
 
 ---
 
 ## Multiple tools per file
 
-You can export multiple tools from a single file. Each export becomes a separate tool with the name `<filename>_<exportname>`:
+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"
@@ -61,65 +105,23 @@ export const add = tool({
   description: "Add two numbers",
   args: {
     a: tool.schema.number().describe("First number"),
-    b: tool.schema.number().describe("Second 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"),
+    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"
-import { tool } from "@opencode-ai/plugin"
-
-export default tool({
-  description: "Get project information",
-  args: {},
-  async execute(args, context) {
-    // Access context information
-    const { agent, sessionID, messageID } = context
-    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}`
-  },
-})
-```