From ac76c5aba7a872933e3e5c4b7f34ec3dbfda58c5 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Thu, 23 Apr 2026 15:44:41 -0700
Subject: [PATCH] docs(tools): convert exec and image-generation params to
 ParamField

---
 docs/tools/exec.md             | 59 +++++++++++++++++++++++++++-------
 docs/tools/image-generation.md | 51 ++++++++++++++++++++++-------
 2 files changed, 86 insertions(+), 24 deletions(-)

diff --git a/docs/tools/exec.md b/docs/tools/exec.md
index 2f21e98aa25..8c910568fb4 100644
--- a/docs/tools/exec.md
+++ b/docs/tools/exec.md
@@ -12,18 +12,53 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 
 ## Parameters
 
-- `command` (required)
-- `workdir` (defaults to cwd)
-- `env` (key/value overrides)
-- `yieldMs` (default 10000): auto-background after delay
-- `background` (bool): background immediately
-- `timeout` (seconds, default 1800): kill on expiry
-- `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
-- `host` (`auto | sandbox | gateway | node`): where to execute
-- `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
-- `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
-- `node` (string): node id/name for `host=node`
-- `elevated` (bool): request elevated mode (escape the sandbox onto the configured host path); `security=full` is only forced when elevated resolves to `full`
+<ParamField path="command" type="string" required>
+Shell command to run.
+</ParamField>
+
+<ParamField path="workdir" type="string" default="cwd">
+Working directory for the command.
+</ParamField>
+
+<ParamField path="env" type="object">
+Key/value environment overrides merged on top of the inherited environment.
+</ParamField>
+
+<ParamField path="yieldMs" type="number" default="10000">
+Auto-background the command after this delay (ms).
+</ParamField>
+
+<ParamField path="background" type="boolean" default="false">
+Background the command immediately instead of waiting for `yieldMs`.
+</ParamField>
+
+<ParamField path="timeout" type="number" default="1800">
+Kill the command after this many seconds.
+</ParamField>
+
+<ParamField path="pty" type="boolean" default="false">
+Run in a pseudo-terminal when available. Use for TTY-only CLIs, coding agents, and terminal UIs.
+</ParamField>
+
+<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
+Where to execute. `auto` resolves to `sandbox` when a sandbox runtime is active and `gateway` otherwise.
+</ParamField>
+
+<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
+Enforcement mode for `gateway` / `node` execution.
+</ParamField>
+
+<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
+Approval prompt behavior for `gateway` / `node` execution.
+</ParamField>
+
+<ParamField path="node" type="string">
+Node id/name when `host=node`.
+</ParamField>
+
+<ParamField path="elevated" type="boolean" default="false">
+Request elevated mode — escape the sandbox onto the configured host path. `security=full` is forced only when elevated resolves to `full`.
+</ParamField>
 
 Notes:
 
diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md
index 18c66645533..28e3e597dbd 100644
--- a/docs/tools/image-generation.md
+++ b/docs/tools/image-generation.md
@@ -60,18 +60,45 @@ Use `action: "list"` to inspect available providers and models at runtime:
 
 ## Tool parameters
 
-| Parameter     | Type     | Description                                                                           |
-| ------------- | -------- | ------------------------------------------------------------------------------------- |
-| `prompt`      | string   | Image generation prompt (required for `action: "generate"`)                           |
-| `action`      | string   | `"generate"` (default) or `"list"` to inspect providers                               |
-| `model`       | string   | Provider/model override, e.g. `openai/gpt-image-2`                                    |
-| `image`       | string   | Single reference image path or URL for edit mode                                      |
-| `images`      | string[] | Multiple reference images for edit mode (up to 5)                                     |
-| `size`        | string   | Size hint: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`            |
-| `aspectRatio` | string   | Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
-| `resolution`  | string   | Resolution hint: `1K`, `2K`, or `4K`                                                  |
-| `count`       | number   | Number of images to generate (1–4)                                                    |
-| `filename`    | string   | Output filename hint                                                                  |
+<ParamField path="prompt" type="string" required>
+Image generation prompt. Required for `action: "generate"`.
+</ParamField>
+
+<ParamField path="action" type="'generate' | 'list'" default="generate">
+Use `"list"` to inspect available providers and models at runtime.
+</ParamField>
+
+<ParamField path="model" type="string">
+Provider/model override, e.g. `openai/gpt-image-2`.
+</ParamField>
+
+<ParamField path="image" type="string">
+Single reference image path or URL for edit mode.
+</ParamField>
+
+<ParamField path="images" type="string[]">
+Multiple reference images for edit mode (up to 5).
+</ParamField>
+
+<ParamField path="size" type="string">
+Size hint: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
+</ParamField>
+
+<ParamField path="aspectRatio" type="string">
+Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
+</ParamField>
+
+<ParamField path="resolution" type="'1K' | '2K' | '4K'">
+Resolution hint.
+</ParamField>
+
+<ParamField path="count" type="number">
+Number of images to generate (1–4).
+</ParamField>
+
+<ParamField path="filename" type="string">
+Output filename hint.
+</ParamField>
 
 Not all providers support all parameters. When a fallback provider supports a nearby geometry option instead of the exact requested one, OpenClaw remaps to the closest supported size, aspect ratio, or resolution before submission. Truly unsupported overrides are still reported in the tool result.