Greptile Summary

This PR improves the tools.profile documentation by expanding terse one-liners into guidance-oriented descriptions, adding a <Note> callout that explains why messaging is intentionally narrow, and providing an explicit profile: "full" example. The changes fit naturally into the existing docs structure and add useful signposting for users surprised by the limited tool surface of a messaging-first setup.

Key observations:

• Per-profile descriptions are accurate and consistent with the tool-groups inventory later in the file.
• The messaging profile description correctly lists restricted tool categories (filesystem, runtime, browser, canvas, nodes, cron, gateway), using "such as" to appropriately signal the list is non-exhaustive.
• The <Note> callout uses valid Mintlify markup and provides correct guidance (profile: "full" for broader access).
• The new profile: "full" example is technically correct; full is documented as "no restriction (same as unset)".
• Minor style note: The <Note> block mixes reference styles—opening with the full dotted path tools.profile but then shortening to profile: "messaging" and profile: "full". Normalizing all three to the full path would improve consistency with how the rest of the document refers to config paths.

Confidence Score: 5/5

• Docs-only change with no runtime impact; all factual claims verified as accurate.
• This is a docs-only change to a single markdown file with no code alterations. Every factual claim in the new content is verifiable against the existing tool-groups inventory in the same file. The only finding is a minor style consistency issue (mixing reference path formats in one sentence), which has no functional impact. The documentation improvements meaningfully enhance discoverability for users experiencing the intentional restrictions of the messaging profile.
• No files require special attention.

_{Last reviewed commit: e53dcf5}

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

Codex automated review: keeping this open.

Keep PR #39954 open. Current main still documents tools.profile as a mechanical profile table and does not include the PR's user-facing clarification that tools.profile: "messaging" is intentionally narrow, nor the direct tools.profile: "full" example for broader command/control access.

Best possible solution:

Keep the PR open and port its useful wording into the current docs/tools/index.md profile section: a compact note that tools.profile: "messaging" is intentionally narrow, tools.profile: "full" is the unrestricted baseline for broader command/control, and a small full-profile example reconciled with the current profile table.

What I checked:

• Current tools docs lack requested guidance: The docs/tools/index.md profile section lists full, coding, messaging, and minimal, plus browser and bundle-MCP caveats, but it does not say messaging-first assistants can feel unexpectedly limited, does not call messaging intentionally narrow, and does not include a tools.profile: "full" example. (docs/tools/index.md:136, e672b61417af)
• Gateway tools docs also remain terse: The gateway tools config page has the same basic profile table and onboarding note, but no practical messaging-vs-full tradeoff explanation. Public docs: docs/gateway/config-tools.md. (docs/gateway/config-tools.md:15, e672b61417af)
• Config help has not superseded the docs change: tools.profile and agents.list[].tools.profile help still describe generic policy baselines; they do not explain that messaging is intentionally narrow or that full is the broadest/unrestricted surface. (src/config/schema.help.ts:648, e672b61417af)
• Runtime behavior confirms the distinction is real: Current tool definitions put filesystem, runtime, web, memory, and most session-control tools in coding, while only message, selected session tools, and session_status are in messaging; browser is outside both restricted profiles. (src/agents/tool-catalog.ts:53, e672b61417af)
• Tests cover the surprising restriction: The current test suite asserts that tools.profile: "messaging" includes message and sessions_send but excludes sessions_spawn, exec, and browser, so the PR documents intentional behavior rather than proposing a runtime change. (src/agents/pi-tools.create-openclaw-coding-tools.test.ts:363, e672b61417af)
• Discussion and related PRs do not obsolete this PR: Provided PR context shows Greptile found the docs change accurate, with only a style note that the author addressed in PR commit 2360874b77e070cbd95fc8b3a6d7e3b91bdb0509. Related PRs config: clarify tools.profile help text #39963, status: surface global tool profile hints in overview #39996, and docs: add troubleshooting guide for limited tool access #40039 are adjacent open work, not merged replacements for this docs/tools/index.md clarification.

Remaining risk / open question:

• The PR likely needs a rebase or manual port because the current profile table has evolved since its base, including group:web, media tools, tools.alsoAllow, and bundle-MCP wording.
• Wording should be coordinated with adjacent open PRs config: clarify tools.profile help text #39963, status: surface global tool profile hints in overview #39996, and docs: add troubleshooting guide for limited tool access #40039 so docs, config help, status output, and troubleshooting guidance do not drift.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against e672b61417af.

ProjectClownfish pushed a narrow repair to this branch so the original contributor path can stay canonical.

Source PR: #39954
Validation: pnpm check:changed
Contributor credit is preserved in the branch history and PR context.