diff --git a/claude-code/src/config.ts b/claude-code/src/config.ts
index 6d902e8e94..84bb687c06 100644
--- a/claude-code/src/config.ts
+++ b/claude-code/src/config.ts
@@ -6,22 +6,50 @@ const ConfigSchema = z.object({
   engine_url: z.string().default('ws://127.0.0.1:49134'),
   defaults: z
     .object({
-      model: z.string().default(''),
+      model: z.string().default('').describe('Model id or alias; empty = Claude Code default'),
       permission_mode: z
         .enum(['default', 'acceptEdits', 'plan', 'bypassPermissions'])
-        .default('acceptEdits'),
-      max_turns: z.number().int().positive().default(50),
-      cwd: z.string().default(''),
-      append_system_prompt: z.string().default(''),
-      allowed_tools: z.array(z.string()).default([]),
-      disallowed_tools: z.array(z.string()).default([]),
+        .default('acceptEdits')
+        .describe('Claude Code permission mode for headless turns'),
+      max_turns: z
+        .number()
+        .int()
+        .positive()
+        .default(50)
+        .describe('Max agent turns before the run stops'),
+      cwd: z.string().default('').describe('Default working directory a turn runs in'),
+      append_system_prompt: z
+        .string()
+        .default('')
+        .describe('Text appended to the Claude Code system prompt'),
+      allowed_tools: z
+        .array(z.string())
+        .default([])
+        .describe('Tools Claude Code may use (empty = its default set)'),
+      disallowed_tools: z.array(z.string()).default([]).describe('Tools Claude Code may never use'),
     })
-    .prefault({}),
-  approval_gate: z.boolean().default(false),
-  events_stream: z.string().default('agent::events'),
-  raw_events_stream: z.string().default('claude::events'),
-  iii_context: z.boolean().default(true),
-  claude_executable: z.string().default(''),
+    .prefault({})
+    .describe('Per-turn defaults applied when a claude::run payload omits a field'),
+  approval_gate: z
+    .boolean()
+    .default(false)
+    .describe('Route tool calls through the approval-gate worker'),
+  events_stream: z
+    .string()
+    .default('agent::events')
+    .describe('Stream carrying the translated AgentEvent frames'),
+  raw_events_stream: z
+    .string()
+    .default('claude::events')
+    .describe('Stream carrying the raw Claude Code messages, verbatim'),
+  iii_context: z
+    .boolean()
+    .default(true)
+    .describe('Prepend the iii runtime context so the agent discovers engine functions'),
+  claude_executable: z
+    .string()
+    .default('')
+    .describe('Path to the claude CLI; empty = resolve on PATH'),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;
diff --git a/codex/src/config.rs b/codex/src/config.rs
index ece88c72d3..02a8cd94eb 100644
--- a/codex/src/config.rs
+++ b/codex/src/config.rs
@@ -12,11 +12,20 @@ use serde_json::Value;
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(default)]
 pub struct Defaults {
+    /// Model id used when a run omits one. Empty = the Codex CLI's own default.
     pub model: String,
+    /// Codex sandbox mode: read-only | workspace-write | danger-full-access.
     pub sandbox_mode: String,
+    /// Codex approval policy: never | on-request | on-failure | untrusted.
+    /// Headless callers leave it at never.
     pub approval_policy: String,
+    /// Model reasoning effort: minimal | low | medium | high | xhigh.
+    /// Empty = the Codex default.
     pub reasoning_effort: String,
+    /// Default working directory a turn runs in when a run omits `cwd`.
+    /// Empty = the worker's process directory.
     pub cwd: String,
+    /// Allow running outside a git repository (skip the repo check).
     pub skip_git_repo_check: bool,
 }
 
@@ -36,11 +45,21 @@ impl Default for Defaults {
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(default)]
 pub struct Config {
+    /// Per-turn defaults applied when a `codex::run` payload omits a field.
     pub defaults: Defaults,
+    /// Stream that carries the translated AgentEvent frames (what the console
+    /// and acp worker render). Grouped by session_id.
     pub events_stream: String,
+    /// Stream that carries the raw Codex thread events, verbatim. Grouped by
+    /// session_id.
     pub raw_events_stream: String,
+    /// Path to the Codex CLI binary. Empty = resolve `codex` on PATH.
     pub codex_executable: String,
+    /// Override the API base URL (passed to the SDK as baseUrl). Empty =
+    /// default.
     pub base_url: String,
+    /// Prepend the iii runtime context to the turn so the agent discovers and
+    /// calls engine functions through the `iii` CLI.
     pub iii_context: bool,
 }
 
diff --git a/opencode/src/config.ts b/opencode/src/config.ts
index b2ebd81125..1fbe567a40 100644
--- a/opencode/src/config.ts
+++ b/opencode/src/config.ts
@@ -6,15 +6,31 @@ const ConfigSchema = z.object({
   engine_url: z.string().default('ws://127.0.0.1:49134'),
   defaults: z
     .object({
-      model: z.string().default(''),
-      cwd: z.string().default(''),
-      agent: z.string().default(''),
+      model: z
+        .string()
+        .default('')
+        .describe('Model id used when a run omits one; empty = OpenCode default'),
+      cwd: z.string().default('').describe('Default working directory a turn runs in'),
+      agent: z.string().default('').describe('Named OpenCode agent to run the turn as'),
     })
-    .prefault({}),
-  events_stream: z.string().default('agent::events'),
-  raw_events_stream: z.string().default('opencode::events'),
-  iii_context: z.boolean().default(true),
-  opencode_executable: z.string().default(''),
+    .prefault({})
+    .describe('Per-turn defaults applied when an opencode::run payload omits a field'),
+  events_stream: z
+    .string()
+    .default('agent::events')
+    .describe('Stream carrying the translated AgentEvent frames'),
+  raw_events_stream: z
+    .string()
+    .default('opencode::events')
+    .describe('Stream carrying the raw OpenCode JSON events, verbatim'),
+  iii_context: z
+    .boolean()
+    .default(true)
+    .describe('Prepend the iii runtime context so the agent discovers engine functions'),
+  opencode_executable: z
+    .string()
+    .default('')
+    .describe('Path to the opencode CLI; empty = resolve on PATH'),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;
diff --git a/pi/src/config.ts b/pi/src/config.ts
index 6dc8b3cba9..8b2cbfc8be 100644
--- a/pi/src/config.ts
+++ b/pi/src/config.ts
@@ -6,18 +6,32 @@ const ConfigSchema = z.object({
   engine_url: z.string().default('ws://127.0.0.1:49134'),
   defaults: z
     .object({
-      model: z.string().default(''),
+      model: z
+        .string()
+        .default('')
+        .describe('Model id used when a run omits one; empty = Pi default'),
       thinking_level: z
         .enum(['off', 'minimal', 'low', 'medium', 'high', 'xhigh'])
-        .default('medium'),
-      cwd: z.string().default(''),
-      tools: z.array(z.string()).default([]),
-      agent_dir: z.string().default(''),
+        .default('medium')
+        .describe('Reasoning effort for the turn'),
+      cwd: z.string().default('').describe('Default working directory a turn runs in'),
+      tools: z.array(z.string()).default([]).describe('Tools Pi may use (empty = its default set)'),
+      agent_dir: z.string().default('').describe('Directory of custom Pi agent definitions'),
     })
-    .prefault({}),
-  events_stream: z.string().default('agent::events'),
-  raw_events_stream: z.string().default('pi::events'),
-  iii_context: z.boolean().default(true),
+    .prefault({})
+    .describe('Per-turn defaults applied when a pi::run payload omits a field'),
+  events_stream: z
+    .string()
+    .default('agent::events')
+    .describe('Stream carrying the translated AgentEvent frames'),
+  raw_events_stream: z
+    .string()
+    .default('pi::events')
+    .describe('Stream carrying the raw Pi events, verbatim'),
+  iii_context: z
+    .boolean()
+    .default(true)
+    .describe('Prepend the iii runtime context so the agent discovers engine functions'),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;