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: N4darae@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.
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 requestpays: eagerly-loaded built-in tool schemas.
Nothing in the README states that
permissions.denyon a built-in also keeps that tool'sschema 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.
Workflowis the largest single item in the tool block.Measured on v2.1.247,
--model opus, first API request of a headless run, summinginput_tokens + cache_creation_input_tokens + cache_read_input_tokens, all rows back toback in one unchanged environment:
deny: [Workflow]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
Tipsbullet. Patch is ready on a publicbranch, since this repo does not currently accept pull requests from outside accounts
(
CreatePullRequestreturnsFORBIDDEN; the same call onanthropics/anthropic-sdk-pythonand
anthropics/claude-code-actionis accepted, so the restriction is specific to this repo):Branch: https://github.com/N4darae/claude-code/tree/N4darae/settings-deny-unused-tools
Commit: N4darae@0a21cc7
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 aninteractive session's -
Artifact,AskUserQuestionandSendFeedbackare absent there,so this measurement cannot price them.
Impact
Medium - Makes feature difficult to understand
Additional Context
Related bug filed as #90059:
disallowedToolsinsettings.jsondoes not trim schemaswhile the identically-named CLI flag
--disallowedToolsdoes. This example therefore usespermissions.deny, which does trim.