refactor: update tool descriptions for clarity and conciseness

- Revised descriptions for various tools in model_tools.py, browser_tool.py, code_execution_tool.py, delegate_tool.py, and terminal_tool.py to enhance clarity and reduce verbosity.
- Improved consistency in terminology and formatting across tool descriptions, ensuring users have a clearer understanding of tool functionalities and usage.

tools/browser_tool.py

@@ -281,7 +281,7 @@ atexit.register(_stop_browser_cleanup_thread)
 BROWSER_TOOL_SCHEMAS = [
     {
         "name": "browser_navigate",
-        "description": "Navigate to a URL in the browser. Opens the page and waits for it to load. Returns the final URL and page title. IMPORTANT: This should be the FIRST browser tool called - it initializes the browser session and loads the target page. Other browser tools require a page to be loaded first. NOTE: For simple information retrieval, prefer using web_search or web_extract first as they are faster and more cost-effective. Use browser tools when you need to interact with a page (click buttons, fill forms, handle dynamic content).",
+        "description": "Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer web_search or web_extract (faster, cheaper). Use browser tools when you need to interact with a page (click, fill forms, dynamic content).",
         "parameters": {
             "type": "object",
             "properties": {
@@ -295,7 +295,7 @@ BROWSER_TOOL_SCHEMAS = [
     },
     {
         "name": "browser_snapshot",
-        "description": "Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) that can be used with browser_click and browser_type. Use full=true to get the complete page content including all text; use full=false (default) for a compact view focused on interactive elements. Requires browser_navigate to be called first.",
+        "description": "Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: complete page content. Snapshots over 8000 chars are truncated or LLM-summarized. Requires browser_navigate first.",
         "parameters": {
             "type": "object",
             "properties": {

tools/code_execution_tool.py

@@ -553,12 +553,14 @@ EXECUTE_CODE_SCHEMA = {
         "    Lines are 1-indexed. Returns {\"content\": \"...\", \"total_lines\": N}\n"
         "  write_file(path: str, content: str) -> dict\n"
         "    Always overwrites the entire file.\n"
-        "  search_files(pattern: str, target=\"grep\", path=\".\", file_glob=None, limit=50) -> dict\n"
-        "    target: \"grep\" (search inside files) or \"find\" (find files by name). Returns {\"matches\": [...]}\n"
+        "  search_files(pattern: str, target=\"content\", path=\".\", file_glob=None, limit=50) -> dict\n"
+        "    target: \"content\" (search inside files) or \"files\" (find files by name). Returns {\"matches\": [...]}\n"
         "  patch(path: str, old_string: str, new_string: str, replace_all: bool = False) -> dict\n"
         "    Replaces old_string with new_string in the file.\n"
         "  terminal(command: str, timeout=None, workdir=None) -> dict\n"
         "    Foreground only (no background/pty). Returns {\"output\": \"...\", \"exit_code\": N}\n\n"
+        "Limits: 5-minute timeout, 50KB stdout cap, max 50 tool calls per script. "
+        "terminal() is foreground-only (no background or pty).\n\n"
         "Print your final result to stdout. Use Python stdlib (json, re, math, csv, "
         "datetime, collections, etc.) for processing between tool calls."
     ),

tools/delegate_tool.py

@@ -331,7 +331,7 @@ DELEGATE_TASK_SCHEMA = {
         "Each subagent gets its own conversation, terminal session, and toolset. "
         "Only the final summary is returned -- intermediate tool results "
         "never enter your context window.\n\n"
-        "TWO MODES:\n"
+        "TWO MODES (one of 'goal' or 'tasks' is required):\n"
         "1. Single task: provide 'goal' (+ optional context, toolsets)\n"
         "2. Batch (parallel): provide 'tasks' array with up to 3 items. "
         "All run concurrently and results are returned together.\n\n"

tools/terminal_tool.py

@@ -1194,43 +1194,13 @@ class _ModalEnvironment:
 
 
 # Tool description for LLM
-TERMINAL_TOOL_DESCRIPTION = """Execute commands on a secure Linux environment.
+TERMINAL_TOOL_DESCRIPTION = """Execute commands on a Linux environment. Filesystem persists between calls.
 
-**Environment:**
-- Isolated execution environment (local, Docker, or Modal cloud based on configuration)
-- Filesystem persists between tool calls within the same task
-- Internet access available
+Background processes: Set background=true to get a session_id, then use the 'process' tool to poll/wait/kill/write.
+Working directory: Use 'workdir' for per-command cwd.
+PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL).
 
-**Command Execution:**
-- Simple commands: Just provide the 'command' parameter
-- Background processes: Set 'background': true to get a session_id for monitoring via the 'process' tool
-- Command timeout: Optional 'timeout' parameter in seconds
-- Working directory: Optional 'workdir' parameter for per-command cwd
-- PTY mode: Set 'pty': true for interactive CLI tools (Codex, Claude Code, etc.)
-
-**Examples:**
-- Run command: `{"command": "ls -la"}`
-- Background task: `{"command": "pytest -v tests/", "background": true}` -- returns session_id, use process tool to poll/wait/kill
-- With workdir: `{"command": "npm install", "workdir": "/home/user/project"}`
-- With timeout: `{"command": "long_task.sh", "timeout": 300}`
-- Interactive CLI: `{"command": "codex exec 'Add tests'", "background": true, "pty": true}`
-
-**Background Process Workflow:**
-1. Start: `terminal(command="...", background=true)` -- returns session_id
-2. Monitor: `process(action="poll", session_id="...")` -- check status + new output
-3. Wait: `process(action="wait", session_id="...", timeout=600)` -- block until done
-4. Interact: `process(action="write/submit", session_id="...", data="y")` -- send stdin
-5. Kill: `process(action="kill", session_id="...")` -- terminate
-
-**Best Practices:**
-- Use background mode for long-running tasks, then process(wait) to block until completion
-- Use workdir to run commands in specific project directories
-- Install whatever tools you need with apt-get or pip
-- Try to create or use a venv with uv or python -m venv to keep isolation from global system packages
-
-**Things to avoid:**
-- Do NOT use interactive tools (vim, nano, python repl) without pty=true -- they will hang without a pseudo-terminal.
-- Even git sometimes becomes interactive if the output is large. If you're not sure, pipe to cat.
+Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page.
 """
 
 # Global state for environment lifecycle management