Summary

• clarify the schema help text for tools.profile
• clarify the schema help text for agents.list[].tools.profile
• explain that messaging is intentionally narrow and full provides the broadest command/control surface

Why

A valid tools.profile setting can still be surprising in practice. In messaging-first setups, tools.profile: "messaging" can make an assistant feel unexpectedly limited even though the behavior is intentional. This change makes that tradeoff clearer directly in config help text, where users encounter it during setup.

Changes

• update tools.profile help text to describe its practical effect on the default tool surface
• call out messaging vs full explicitly
• update per-agent agents.list[].tools.profile help text with a concrete override example

What did not change

• no runtime behavior
• no schema values or validation rules
• no tool policy logic

Change Type

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related docs: clarify messaging vs full tool profiles #39954

User-visible / Behavior Changes

Users reading generated config help text will get clearer guidance about when messaging is intentionally restrictive and when full is a better fit. No runtime behavior changes.

Security Impact

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: Windows 11
• Runtime/container: local clone
• Model/provider: n/a
• Integration/channel (if any): n/a
• Relevant config (redacted): tools.profile, agents.list[].tools.profile

Steps

1. Open src/config/schema.help.ts
2. Inspect the help text for tools.profile and agents.list[].tools.profile
3. Compare before/after wording

Expected

• help text explains the practical difference between narrower and broader profile choices
• users can understand why a messaging-first setup may feel limited

Actual

• updated help text now calls out messaging and full directly and gives a clearer per-agent override example

Evidence

• Trace/log snippets
• Failing test/log before + passing after
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification

• Verified scenarios: reviewed the exact diff and confirmed the wording matches current documented profile behavior
• Edge cases checked: per-agent override wording remains additive/helpful without implying behavior changes
• What you did not verify: full local test execution in this clone environment

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this commit
• Files/config to restore: src/config/schema.help.ts
• Known bad symptoms reviewers should watch for: misleading wording or overclaiming behavior

Risks and Mitigations

• Risk: wording may be considered too prescriptive for help text
• Mitigation: kept the change limited to clarifying current documented behavior without changing schema or runtime