diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs
index cc758eaedf..c33904e2fd 100644
--- a/codex-rs/core/src/codex.rs
+++ b/codex-rs/core/src/codex.rs
@@ -536,7 +536,7 @@ impl Session {
 
         for (alias, feature) in config.features.legacy_feature_usages() {
             let canonical = feature.key();
-            let summary = format!("`{alias}` is deprecated. Use `{canonical}` instead.");
+            let summary = format!("`{alias}` is deprecated. Use `[features].{canonical}` instead.");
             let details = if alias == canonical {
                 None
             } else {
diff --git a/codex-rs/core/tests/suite/deprecation_notice.rs b/codex-rs/core/tests/suite/deprecation_notice.rs
index 4e240f0a07..bab715ebd8 100644
--- a/codex-rs/core/tests/suite/deprecation_notice.rs
+++ b/codex-rs/core/tests/suite/deprecation_notice.rs
@@ -36,7 +36,7 @@ async fn emits_deprecation_notice_for_legacy_feature_flag() -> anyhow::Result<()
     let DeprecationNoticeEvent { summary, details } = notice;
     assert_eq!(
         summary,
-        "`use_experimental_unified_exec_tool` is deprecated. Use `unified_exec` instead."
+        "`use_experimental_unified_exec_tool` is deprecated. Use `[features].unified_exec` instead."
             .to_string(),
     );
     assert_eq!(
diff --git a/docs/config.md b/docs/config.md
index b7d44142aa..08ff2aa349 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -350,6 +350,8 @@ Though using this option may also be necessary if you try to use Codex in enviro
 
 ### tools.\*
 
+These `[tools]` configuration options are deprecated. Use `[features]` instead (see [Feature flags](#feature-flags)).
+
 Use the optional `[tools]` table to toggle built-in tools that the agent may call. `web_search` stays off unless you opt in, while `view_image` is now enabled by default:
 
 ```toml
@@ -358,8 +360,6 @@ web_search = true   # allow Codex to issue first-party web searches without prom
 view_image = false  # disable image uploads (they're enabled by default)
 ```
 
-`web_search` is deprecated; use the `web_search_request` feature flag instead.
-
 The `view_image` toggle is useful when you want to include screenshots or diagrams from your repo without pasting them manually. Codex still respects sandboxing: it can only attach files inside the workspace roots you allow.
 
 ### approval_presets