Repository navigation
[docs] docs: unbloat reference/tools.md - #77002
Conversation
Condense verbose prose in the Web Tools, agentic-workflows, cli-proxy, Custom CA Certificates, and Learn More sections. Engine web-search behavior is now a bullet list. Code blocks, links, and technical constraints are preserved.
There was a problem hiding this comment.
🟡 Changes recommended
The change still has active documentation issues because it removes important security, runtime-home, and launcher path-resolution details from the tools reference.
3 open issues
What changed in this PR
Condenses the tools reference documentation while retaining configuration examples, engine-specific behavior, and links to detailed reference pages.
Changes:
- Shortens connector, memory, Playwright, QMD, and Learn More descriptions.
- Consolidates engine-specific web-search guidance.
- Streamlines CLI mounting, timeout, CA certificate, and MCP server documentation.
| File | Description |
|---|---|
| docs/src/content/docs/reference/tools.md | Condensed reference prose and configuration guidance across the tools documentation page while preserving its examples and core technical details. |
Review effort: Lite (auto)
| See [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) for available operations. | ||
|
|
||
| The built-in container runs with the runner's UID and GID unless a container user is explicitly configured. This keeps downloaded logs runner-owned without widening their owner-only permissions, so the post-agent secret-redaction step can read them. Its default `HOME` is the backend container's ephemeral `/tmp`, not `/root`. Redaction failures still remove unsanitized sources and fail the step. | ||
| The built-in container runs as the runner's UID and GID unless a container user is configured, so downloaded logs stay runner-owned and the post-agent secret-redaction step can read them. Redaction failures still remove unsanitized sources and fail the step. |
| For `add_comment`, use `item_number` rather than `issue_number`; schema validation strips the latter. Prefer one single-quoted JSON object argument for safe outputs. Inside JSON strings, encode newlines as `\n`, double quotes as `\"`, backslashes as `\\`, and apostrophes as `\u0027`; Unicode can remain literal. Stdin is also supported: `safeoutputs <tool_name> .` reads a complete JSON object from stdin. This does not grant permission for helper commands or redirections. No auxiliary tools, pipelines, temporary files, or shell expansion are needed for inline JSON. | ||
|
|
||
| CLI mounting changes only the agent-facing interface: the MCP gateway still starts normally, but mounted servers are removed from the MCP tool list and accessed via shell. This can reduce token use from large tool schemas and simplify prompts when shell-style invocation is preferred. | ||
| For `add_comment`, use `item_number`, not `issue_number` (schema validation strips the latter). Pass safe-output arguments as one single-quoted JSON object, encoding newlines as `\n`, double quotes as `\"`, backslashes as `\\`, and apostrophes as `\u0027`. Stdin also works: `safeoutputs <tool_name> .` reads a complete JSON object from stdin. |
| ``` | ||
|
|
||
| The path is relative to `GITHUB_WORKSPACE`, or an absolute Linux host path. For a custom checkout path such as `checkout: { path: target }`, include that directory: `ca-cert-file: target/.github/certs/internal-ca.pem`. The exact prefixes `${{ github.workspace }}/` and `${{ runner.temp }}/` are also supported. Paths may contain letters, digits, spaces, `_`, `.`, `/`, and `-`; parent-directory traversal, shell substitutions, and other expressions are rejected. The file must exist and be readable by the runner before the **Start MCP Gateway** step. The launcher resolves symlinks and mounts only that file read-only at a gateway-private path, including when `sandbox.mcp.mounts` overrides the defaults. No extra gateway mount configuration is needed. | ||
| The path is relative to `GITHUB_WORKSPACE` or an absolute Linux host path. For a custom checkout path such as `checkout: { path: target }`, include that directory (`target/.github/certs/internal-ca.pem`). The `${{ github.workspace }}/` and `${{ runner.temp }}/` prefixes are also supported. Paths may contain letters, digits, spaces, `_`, `.`, `/`, and `-`; traversal and other expressions are rejected. The file must exist and be readable before the **Start MCP Gateway** step. The gateway mounts only that file, read-only, even when `sandbox.mcp.mounts` overrides the defaults. |
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality SentinelOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
🎉 This pull request is included in a new release. Release: |

Summary
Condenses
docs/src/content/docs/reference/tools.md, the only file changed. Word count drops from 1,907 to 1,523 (about 20%); line count drops from 301 to 284.Bloat removed
Preserved
--allow-write-toolsscope,cli-proxyandgh-proxyrejection without bash,ca-cert-filepath rules and gateway mount behavior, the Codexweb_searchtoggle, timeout precedence, andrequired: falsesemantics./reference/web-search/link, which remains in the Copilot/Gemini paragraph.Notes
The file was selected from the uncleaned candidate list. It has no
disable-agentic-editingflag. The branch was created frommain. Pre-existing unrelated working-tree changes were left unstaged and are not part of this PR.References: none