From 5e3bccd96c8eed336d2b7ccd1419ca6722a54cb9 Mon Sep 17 00:00:00 2001 From: Matt Vollmer Date: Mon, 30 Mar 2026 16:24:45 -0400 Subject: [PATCH] docs: fix tool tables and model option errors in agent docs (#23821) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes factual errors found during a review of all pages under `/docs/ai-coder/agents/`. ## Tool tables (`index.md`, `architecture.md`) Both pages had incomplete tool tables. Added: - `process_output`, `process_list`, `process_signal` — core workspace tools always registered alongside `execute`, missing from both pages - `propose_plan` — platform tool (root chats only), missing from both pages - `spawn_computer_use_agent` — orchestration tool (conditional), missing from architecture.md Also fixed the architecture.md claim that the agent is "restricted to the tool set defined in this section" — it now mentions skills and MCP tools with links to the relevant pages. ## Model options (`models.md`) - **OpenAI / OpenRouter Reasoning Effort**: docs listed `low`, `medium`, `high` — code has `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. Fixed both. - **Removed hidden fields** that never appear in the admin UI: - Google: Safety Settings (`hidden:"true"`) - OpenRouter: Provider Order, Allow Fallbacks (parent struct `hidden:"true"`) - Vercel: Provider Options (`hidden:"true"`) --- *PR generated with Coder Agents* --- docs/ai-coder/agents/architecture.md | 39 ++++++++++++++++------------ docs/ai-coder/agents/index.md | 6 ++++- docs/ai-coder/agents/models.md | 30 ++++++++++----------- 3 files changed, 41 insertions(+), 34 deletions(-) diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index 0995a51770..8b12f98663 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -106,10 +106,15 @@ Tools are how the agent takes action. Each tool call from the LLM translates to a concrete operation — either inside a workspace or within the control plane itself. -The agent is restricted to the tool set defined in this section. It has no -direct access to the Coder API beyond what these tools expose and cannot -execute arbitrary operations against the control plane. If a capability is -not represented by a tool, the agent cannot perform it. +The agent is restricted to the built-in tool set defined in this section, +plus any additional tools from workspace skills and MCP servers. Skills +provide structured instructions the agent loads on demand +(see [Extending Agents](./extending-agents.md)). MCP tools come from +admin-configured external servers +(see [MCP Servers](./platform-controls/mcp-servers.md)) and from workspace +`.mcp.json` files. The agent has no direct access to the Coder API beyond +what these tools expose and cannot execute arbitrary operations against the +control plane. ### Workspace connection lifecycle @@ -144,24 +149,26 @@ workspace connection. Platform and orchestration tools are only available to root chats — sub-agents spawned by `spawn_agent` do not have access to them and cannot create workspaces or spawn further sub-agents. -| Tool | What it does | -|--------------------|----------------------------------------------------------------------------------------| -| `list_templates` | Browses available workspace templates, sorted by popularity. | -| `read_template` | Gets template details and configurable parameters. | -| `create_workspace` | Creates a workspace from a template and waits for it to be ready. | -| `start_workspace` | Starts the chat's workspace if it is currently stopped. Idempotent if already running. | +| Tool | What it does | +|--------------------|-----------------------------------------------------------------------------------------| +| `list_templates` | Browses available workspace templates, sorted by popularity. | +| `read_template` | Gets template details and configurable parameters. | +| `create_workspace` | Creates a workspace from a template and waits for it to be ready. | +| `start_workspace` | Starts the chat's workspace if it is currently stopped. Idempotent if already running. | +| `propose_plan` | Presents a Markdown plan file from the workspace for user review before implementation. | ### Orchestration tools These tools manage sub-agents — child chats that work on independent tasks in parallel. -| Tool | What it does | -|-----------------|--------------------------------------------------------------| -| `spawn_agent` | Delegates a task to a sub-agent with its own context window. | -| `wait_agent` | Waits for a sub-agent to finish and collects its result. | -| `message_agent` | Sends a follow-up message to a running sub-agent. | -| `close_agent` | Stops a running sub-agent. | +| Tool | What it does | +|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `spawn_agent` | Delegates a task to a sub-agent with its own context window. | +| `wait_agent` | Waits for a sub-agent to finish and collects its result. | +| `message_agent` | Sends a follow-up message to a running sub-agent. | +| `close_agent` | Stops a running sub-agent. | +| `spawn_computer_use_agent` | Spawns a sub-agent with desktop interaction capabilities (screenshot, mouse, keyboard). Requires an Anthropic provider and the desktop feature to be enabled by an administrator. | ### Provider tools diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index d12540aef5..b59338e8a9 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -238,10 +238,14 @@ tasks: | `read_template` | Get template details and configurable parameters | | `create_workspace` | Create a workspace from a template | | `start_workspace` | Start a stopped workspace for the current chat | +| `propose_plan` | Present a Markdown plan file for user review | | `read_file` | Read file contents from the workspace | | `write_file` | Write a file to the workspace | | `edit_files` | Perform search-and-replace edits across files | | `execute` | Run shell commands in the workspace | +| `process_output` | Retrieve output from a background process | +| `process_list` | List all tracked processes in the workspace | +| `process_signal` | Send a signal (terminate/kill) to a tracked process | | `spawn_agent` | Delegate a task to a sub-agent running in parallel | | `wait_agent` | Wait for a sub-agent to complete and collect its result | | `message_agent` | Send a follow-up message to a running sub-agent | @@ -253,7 +257,7 @@ web terminals and IDE access. No additional ports or services are required in the workspace. Platform tools (`list_templates`, `read_template`, `create_workspace`, -`start_workspace`) and orchestration tools (`spawn_agent`) +`start_workspace`, `propose_plan`) and orchestration tools (`spawn_agent`) are only available to root chats. Sub-agents do not have access to these tools and cannot create workspaces or spawn further sub-agents. diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md index ec2018c5fd..be5a3579fe 100644 --- a/docs/ai-coder/agents/models.md +++ b/docs/ai-coder/agents/models.md @@ -132,11 +132,11 @@ fields appear dynamically in the admin UI when you select a provider. #### OpenAI -| Option | Description | -|-----------------------|-----------------------------------------------------------------------| -| Reasoning Effort | How much effort the model spends reasoning (`low`, `medium`, `high`). | -| Max Completion Tokens | Cap on completion tokens for reasoning models. | -| Parallel Tool Calls | Whether the model can call multiple tools at once. | +| Option | Description | +|-----------------------|---------------------------------------------------------------------------------------------------| +| Reasoning Effort | How much effort the model spends reasoning (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). | +| Max Completion Tokens | Cap on completion tokens for reasoning models. | +| Parallel Tool Calls | Whether the model can call multiple tools at once. | #### Google @@ -144,24 +144,20 @@ fields appear dynamically in the admin UI when you select a provider. |------------------|-----------------------------------------------------| | Thinking Budget | Maximum tokens for the model's internal reasoning. | | Include Thoughts | Whether to include thinking traces in the response. | -| Safety Settings | Content safety thresholds by category. | #### OpenRouter -| Option | Description | -|-------------------|---------------------------------------------------| -| Reasoning Enabled | Enable extended reasoning mode. | -| Reasoning Effort | Reasoning effort level (`low`, `medium`, `high`). | -| Provider Order | Preferred provider routing order. | -| Allow Fallbacks | Whether to fall back to alternative providers. | +| Option | Description | +|-------------------|-------------------------------------------------------------------------------| +| Reasoning Enabled | Enable extended reasoning mode. | +| Reasoning Effort | Reasoning effort level (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). | #### Vercel AI Gateway -| Option | Description | -|-------------------|-----------------------------------------------| -| Reasoning Enabled | Enable extended reasoning mode. | -| Reasoning Effort | Reasoning effort level. | -| Provider Options | Routing preferences for underlying providers. | +| Option | Description | +|-------------------|---------------------------------| +| Reasoning Enabled | Enable extended reasoning mode. | +| Reasoning Effort | Reasoning effort level. | > [!NOTE] > Azure OpenAI uses the same options as OpenAI. AWS Bedrock uses the same