docs/tool-reference.md omits evaluate_script's serviceWorkerId and marks pageId required, contrary to the skill and CLI docs #3015

Description of the bug

The chrome-devtools skill and docs/cli.md tell agents to call evaluate_script with serviceWorkerId (and without pageId) to run code in an extension service worker. The generated tool reference documents evaluate_script with pageId (required) and no serviceWorkerId parameter, even though it documents the extension tools themselves. With --categoryExtensions, tools/list exposes serviceWorkerId and makes pageId optional. An agent or user that checks the documented parameters in docs/tool-reference.md cannot find the parameter the other docs tell it to use.

Actual behavior

docs/tool-reference.md lists, for evaluate_script, - **pageId** (number) **(required)**: Targets a specific page by ID. and no serviceWorkerId on both the tag and main. The tools/list schemas observed:

1.10.1 default:              required ["pageId","function"]  no serviceWorkerId
1.10.1 --categoryExtensions: required ["function"]           serviceWorkerId present
main   default:              required ["pageId"]             no serviceWorkerId
main   --categoryExtensions: required (none)                 serviceWorkerId present

On main the serviceWorkerId description is "The optional service worker id to evaluate the script in. If provided, 'pageId' should be omitted. Note: 'args' (element UIDs) cannot be used when evaluating in a service worker." and the pageId description is "Targets a specific page by ID. Required when not evaluating in a service worker." From source: scripts/generate-docs.ts:415 on main builds the reference from createTools({pageIdRouting: true}), so parameters added only when categoryExtensions is set (src/tools/script.ts, ...(cliArgs.categoryExtensions ? {serviceWorkerId: ...} : {})) never reach the generated page. The same generator setting omits the extension-specific description text of list_pages and list_console_messages.

Reproduction

1. Read the evaluate_script section of docs/tool-reference.md (at tag chrome-devtools-mcp-v1.10.1 and on main).
2. Start each tested build over stdio with --headless --isolated --no-usage-statistics --no-performance-crux --categoryExtensions, send tools/list, and read the evaluate_script input schema. Repeat without --categoryExtensions.

Expectation

skills/chrome-devtools/SKILL.md:15 says: "For evaluate_script, pageId is required when targeting pages. However, when --categoryExtensions is enabled, pageId is optional so you can pass serviceWorkerId instead to evaluate inside an extension background service worker." skills/chrome-devtools/SKILL.md:64 and docs/cli.md:79-89 give the same instruction with --serviceWorkerId. The tool reference documents the extension tools, so its evaluate_script entry should document serviceWorkerId and the conditional pageId requirement under --categoryExtensions.

MCP configuration

--headless --isolated --no-usage-statistics --no-performance-crux unless the reproduction states otherwise (update checks disabled with CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1).

Chrome DevTools MCP version

1.10.1 (npm) and main 5ddb0a3 (local build)

Chrome version

154.0.8037.98 (stable)

Node version

v22.23.2

Operating system

macOS 27.0

Environment details

• Release build: chrome-devtools-mcp@1.10.1 from npm.
• main build: local build of main at 5ddb0a3.
• Google Chrome 154.0.8037.98 (stable), Node v22.23.2, macOS 27.

Evidence

• Expected source: skills/chrome-devtools/SKILL.md:15,64 and docs/cli.md:79-89 (instructions to pass serviceWorkerId); tools/list with --categoryExtensions on both tested builds.
• Failure source: docs/tool-reference.md, evaluate_script section, on the tag and main; scripts/generate-docs.ts:415 and src/tools/script.ts for how the parameter is dropped.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The full open and closed issue and PR corpus was screened as of 2026-10-06. Related but distinct: #2846 (and open PR #2881) concern what value list_console_messages' serviceWorkerId expects; open PR #2852 corrects CLI availability of extension tools in docs/cli.md; open PR #2878 changes scripts/generate-docs.ts for slim and hidden-flag tools but still generates from createTools({pageIdRouting: true}).

Fix check

Failing now: docs/tool-reference.md shows evaluate_script with pageId required and no serviceWorkerId, while tools/list under --categoryExtensions exposes serviceWorkerId with pageId optional. Restored: the tool reference documents serviceWorkerId for evaluate_script and states that pageId becomes optional when --categoryExtensions is enabled, consistent with tools/list under that flag. Control: the default (no --categoryExtensions) evaluate_script documentation keeps pageId required, matching tools/list without the flag.