[DOCS] examples/settings has no example for per-request context cost

Documentation Type

Missing documentation (feature not documented)

Documentation Location

examples/settings/README.md

Section/Topic

examples/settings - no example covers per-request context cost

Current Documentation

examples/settings/ covers permission and sandbox posture (settings-lax.json,
settings-strict.json, settings-bash-sandbox.json). Nothing covers a cost every request
pays: eagerly-loaded built-in tool schemas.

Nothing in the README states that permissions.deny on a built-in also keeps that tool's
schema out of context. An admin reading the table can reasonably assume denying a tool only
gates the call.

What's Wrong or Missing?

Several built-in tools are opt-in features whose schemas are sent on every request whether
or not the organization uses them. Workflow is the largest single item in the tool block.

Measured on v2.1.247, --model opus, first API request of a headless run, summing
input_tokens + cache_creation_input_tokens + cache_read_input_tokens, all rows back to
back in one unchanged environment:

| settings | input tokens | reclaimed |
|---|---|---|
| none (baseline) | 23,052 | - |
| deny: [Workflow] | 15,152 | 7,900 |
| five opt-in tools denied | 12,166 | 10,886 (-47%) |

The reclaimed column is the reproducible figure; absolute totals also carry the local
CLAUDE.md, memory files and MCP definitions.

Suggested Improvement

Add a fourth example plus one table column and one Tips bullet. Patch is ready on a public
branch, since this repo does not currently accept pull requests from outside accounts
(CreatePullRequest returns FORBIDDEN; the same call on anthropics/anthropic-sdk-python
and anthropics/claude-code-action is accepted, so the restriction is specific to this repo):

Branch: https://github.com/N4darae/claude-code/tree/N4darae/settings-deny-unused-tools
Commit: https://github.com/N4darae/claude-code/commit/0a21cc7

diff --git a/examples/settings/README.md b/examples/settings/README.md
index 34e60ca..dc778ec 100644
--- a/examples/settings/README.md
+++ b/examples/settings/README.md
@@ -10,21 +10,23 @@ These may be applied at any level of the [settings hierarchy](https://code.claud
 > [!WARNING]
 > These examples are community-maintained snippets which may be unsupported or incorrect. You are responsible for the correctness of your own settings configuration.
 
-| Setting | [`settings-lax.json`](./settings-lax.json) | [`settings-strict.json`](./settings-strict.json) | [`settings-bash-sandbox.json`](./settings-bash-sandbox.json) |
-|---------|:---:|:---:|:---:|
-| Disable `--dangerously-skip-permissions` | ✅ | ✅ | |
-| Block plugin marketplaces | ✅ | ✅ | |
-| Block user and project-defined permission `allow` / `ask` / `deny` | | ✅ | ✅ |
-| Block user and project-defined hooks | | ✅ | |
-| Deny web fetch and search tools | | ✅ | |
-| Bash tool requires approval | | ✅ | |
-| Bash tool must run inside of sandbox | | | ✅ |
+| Setting | [`settings-lax.json`](./settings-lax.json) | [`settings-strict.json`](./settings-strict.json) | [`settings-bash-sandbox.json`](./settings-bash-sandbox.json) | [`settings-deny-unused-tools.json`](./settings-deny-unused-tools.json) |
+|---------|:---:|:---:|:---:|:---:|
+| Disable `--dangerously-skip-permissions` | ✅ | ✅ | | |
+| Block plugin marketplaces | ✅ | ✅ | | |
+| Block user and project-defined permission `allow` / `ask` / `deny` | | ✅ | ✅ | |
+| Block user and project-defined hooks | | ✅ | | |
+| Deny web fetch and search tools | | ✅ | | |
+| Bash tool requires approval | | ✅ | | |
+| Bash tool must run inside of sandbox | | | ✅ | |
+| Deny unused opt-in tools to reclaim context | | | | ✅ |
 
 ## Tips
 - Consider merging snippets of the above examples to reach your desired configuration
 - Settings files must be valid JSON
 - Before deploying configuration files to your organization, test them locally by applying to `managed-settings.json`, `settings.json` or `settings.local.json`
 - The `sandbox` property only applies to the `Bash` tool; it does not apply to other tools (like Read, Write, WebSearch, WebFetch, MCPs), hooks, or internal commands
+- `permissions.deny` on a built-in tool keeps that tool's schema out of the context window, not just the tool out of reach. Denying opt-in tools your organization does not use therefore reclaims context on every request: `settings-deny-unused-tools.json` denies `Workflow`, `ScheduleWakeup`, `ReportFindings`, `SendFeedback` and `ShareOnboardingGuide`, reclaiming 10,886 input tokens per request (-47%) in a headless measurement, of which `Workflow` alone is 7,900. The saving is reproducible; the absolute totals are not, since they also carry your `CLAUDE.md`, memory files and MCP tool definitions
 
 ## Deploying via MDM
 
diff --git a/examples/settings/settings-deny-unused-tools.json b/examples/settings/settings-deny-unused-tools.json
new file mode 100644
index 0000000..85acef8
--- /dev/null
+++ b/examples/settings/settings-deny-unused-tools.json
@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "deny": [
+      "Workflow",
+      "ScheduleWakeup",
+      "ReportFindings",
+      "SendFeedback",
+      "ShareOnboardingGuide"
+    ]
+  }
+}

Verified: the shipped file reproduces 12,166 exactly, and the session still completes
normally. Measured in headless (-p) mode, whose tool set is not identical to an
interactive session's - Artifact, AskUserQuestion and SendFeedback are absent there,
so this measurement cannot price them.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related bug filed as #90059: disallowedTools in settings.json does not trim schemas
while the identically-named CLI flag --disallowedTools does. This example therefore uses
permissions.deny, which does trim.