From c4e32ccfe1ebccb6644b657b2f6b84857b35da07 Mon Sep 17 00:00:00 2001
From: Fede Kamelhar <209537060+fede-kamel@users.noreply.github.com>
Date: Wed, 30 Sep 2026 19:52:23 -0400
Subject: [PATCH] docs(tts): explain that restricted tool profiles exclude the
 tts tool (#155950)

The tts catalog entry belongs to no built-in profile, so minimal, coding,
and messaging all remove it with no documented way back. Document the
tools.alsoAllow grant on the agent-tool page and the profile table, and
note that automatic TTS is unaffected by tool profiles.

Refs #126688
---
 docs/gateway/config-tools/tool-policy.md |  5 +++++
 docs/tools/tts/api.md                    | 21 +++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/gateway/config-tools/tool-policy.md b/docs/gateway/config-tools/tool-policy.md
index c1e257a190e1..7758a60a54c1 100644
--- a/docs/gateway/config-tools/tool-policy.md
+++ b/docs/gateway/config-tools/tool-policy.md
@@ -41,6 +41,11 @@ workspace and identity checks or the meeting transcript caller checks.
 `coding` and `messaging` also include the [theme tool](/tools/theme) and implicitly
 allow `bundle-mcp` (configured MCP servers).
 
+The [`tts` tool](/tools/tts/api#tool-profiles) is not part of any restricted
+profile. To let an agent on `minimal`, `coding`, or `messaging` call it, add
+`tts` to `tools.alsoAllow`. [Automatic TTS](/tools/tts/output#auto-tts-behavior)
+is not a tool, so profiles do not affect it.
+
 An unset profile also leaves core tools unfiltered, but does not itself opt into
 optional plugin tools. Explicit `full` contributes a wildcard to plugin tool
 selection, including optional tools from enabled plugins. Plugin configuration,
diff --git a/docs/tools/tts/api.md b/docs/tools/tts/api.md
index 2624a6b7265f..370be1a2eecd 100644
--- a/docs/tools/tts/api.md
+++ b/docs/tools/tts/api.md
@@ -23,6 +23,27 @@ per-call provider request timeout in milliseconds. Per-call values override
 `tts.timeoutMs`; configured TTS timeouts override any plugin-authored
 provider default.
 
+### Tool profiles
+
+`tts` is not part of the `minimal`, `coding`, or `messaging`
+[tool profiles](/gateway/config-tools/tool-policy#tool-profiles). Agents on
+those profiles cannot call it until you grant it explicitly:
+
+```json5
+{
+  tools: {
+    profile: "messaging",
+    alsoAllow: ["tts"],
+  },
+}
+```
+
+The `full` profile and an unset profile include `tts` without extra
+configuration. Other allow/deny layers can still remove it.
+
+Tool profiles do not affect [automatic TTS](/tools/tts/output#auto-tts-behavior):
+`tts.auto` still speaks replies when the agent cannot call the `tts` tool.
+
 ## Gateway RPC
 
 | Method            | Purpose                                      |