fix: configure codex with a longer timeout

refactor: param names

docs/adding_tools.md

@@ -51,9 +51,10 @@ from tools.simple.base import SimpleTool
 
 class ChatRequest(ToolRequest):
     prompt: str = Field(..., description="Your question or idea.")
-    files: list[str] | None = Field(default_factory=list)
-    working_directory: str = Field(
-        ..., description="Absolute full directory path where the assistant AI can save generated code for implementation."
+    absolute_file_paths: list[str] | None = Field(default_factory=list)
+    working_directory_absolute_path: str = Field(
+        ...,
+        description="Absolute path to an existing directory where generated code can be saved.",
     )
 
 class ChatTool(SimpleTool):
@@ -72,15 +73,15 @@ class ChatTool(SimpleTool):
     def get_tool_fields(self) -> dict[str, dict[str, object]]:
         return {
             "prompt": {"type": "string", "description": "Your question."},
-            "files": SimpleTool.FILES_FIELD,
-            "working_directory": {
+            "absolute_file_paths": SimpleTool.FILES_FIELD,
+            "working_directory_absolute_path": {
                 "type": "string",
-                "description": "Absolute full directory path where the assistant AI can save generated code for implementation.",
+                "description": "Absolute path to an existing directory for generated code artifacts.",
             },
         }
 
     def get_required_fields(self) -> list[str]:
-        return ["prompt", "working_directory"]
+        return ["prompt", "working_directory_absolute_path"]
 
     async def prepare_prompt(self, request: ChatRequest) -> str:
         return self.prepare_chat_style_prompt(request)

docs/advanced-usage.md

@@ -395,11 +395,11 @@ User: "Use gemini to review this code: [50,000+ character detailed analysis]"
 Zen MCP: "The prompt is too large for MCP's token limits (>50,000 characters). 
 Please save the prompt text to a temporary file named 'prompt.txt' and resend 
 the request with an empty prompt string and the absolute file path included 
-in the files parameter, along with any other files you wish to share as context."
+in the absolute_file_paths parameter, along with any other files you wish to share as context."
 
 # Claude automatically handles this:
 - Saves your prompt to /tmp/prompt.txt
-- Resends: "Use gemini to review this code" with files=["/tmp/prompt.txt", "/path/to/code.py"]
+- Resends: "Use gemini to review this code" with absolute_file_paths=["/tmp/prompt.txt", "/path/to/code.py"]
 
 # Server processes the large prompt through Gemini's 1M context
 # Returns comprehensive analysis within MCP's response limits

docs/getting-started.md

@@ -141,6 +141,7 @@ Edit `~/.codex/config.toml`:
 [mcp_servers.zen]
 command = "bash"
 args = ["-c", "for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server; done; echo 'uvx not found' >&2; exit 1"]
+tool_timeout_sec = 1200  # 20 minutes; added automatically by the setup script so upstream providers can respond
 
 [mcp_servers.zen.env]
 PATH = "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$HOME/.local/bin:$HOME/.cargo/bin:$HOME/bin"
@@ -304,7 +305,7 @@ CUSTOM_MODEL_NAME=llama3.2                   # Default model name
 
 ## Prevent Client Timeouts
 
-Some MCP clients default to short timeouts and can disconnect from Zen during long tool runs. Configure each client to wait at least five minutes (300 000 ms) before giving up.
+Some MCP clients default to short timeouts and can disconnect from Zen during long tool runs. Configure each client with a generous ceiling (we recommend at least five minutes); the Zen setup script now writes a 20-minute tool timeout for Codex so upstream providers contacted by the server have time to respond.
 
 ### Claude Code & Claude Desktop
 
@@ -330,10 +331,10 @@ Codex exposes per-server timeouts in `~/.codex/config.toml`. Add (or bump) these
 command = "..."
 args = ["..."]
 startup_timeout_sec = 300    # default is 10 seconds
-tool_timeout_sec = 300       # default is 60 seconds
+tool_timeout_sec = 1200      # default is 60 seconds; setup script pre-populates 20 minutes so upstream providers can respond
 ```
 
-`startup_timeout_sec` covers the initial handshake/list tools step, while `tool_timeout_sec` governs each tool call. Increase either beyond 300 if your workflow routinely exceeds five minutes.
+`startup_timeout_sec` covers the initial handshake/list tools step, while `tool_timeout_sec` governs each tool call. Raise the latter if the providers your MCP server invokes routinely need more than 20 minutes.
 
 ### Gemini CLI
 

docs/tools/chat.md

@@ -53,9 +53,9 @@ word verdict in the end.
 
 - `prompt`: Your question or discussion topic (required)
 - `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5|gpt5-mini|gpt5-nano (default: server default)
-- `files`: Optional files for context (absolute paths)
+- `absolute_file_paths`: Optional absolute file or directory paths for additional context
 - `images`: Optional images for visual context (absolute paths)
-- `working_directory`: **Required** - Absolute directory path where generated code artifacts will be saved
+- `working_directory_absolute_path`: **Required** - Absolute path to an existing directory where generated code artifacts will be saved
 - `temperature`: Response creativity (0-1, default 0.5)
 - `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
 - `continuation_id`: Continue previous conversations