Address review feedback:

- Update changie entry
- Have generic deprecated notice when no replacement is set
- Replace description with deprecation text (no old description)

Author: jairus-m

.changes/unreleased/Under the Hood-20260706-101105.yaml

@@ -1,3 +1,3 @@
 kind: Under the Hood
-body: Update docs gen script to add deprecated tools to README
+body: Update docs gen script to annotate deprecated tools to README
 time: 2026-07-06T10:11:05.118226-07:00

scripts/generate_docs.py

@@ -70,15 +70,17 @@ def generate_readme_tools_section() -> str:
 
         sorted_tools = sorted(tool_names, key=lambda t: t.value)
         for tool in sorted_tools:
-            desc = HUMAN_DESCRIPTIONS.get(tool, "")
             meta = _TOOL_META.get(tool)
-            replacement = (
-                meta.get("replacement") if meta and meta.get("deprecated") else None
-            )
-            suffix = (
-                f" *(deprecated — use `{replacement}` instead)*" if replacement else ""
-            )
-            lines.append(f"- `{tool.value}`{suffix}: {desc}")
+            if meta and meta.get("deprecated"):
+                replacement = meta.get("replacement")
+                desc = (
+                    f"*(deprecated — use `{replacement}` instead)*"
+                    if replacement
+                    else "*(deprecated)*"
+                )
+            else:
+                desc = HUMAN_DESCRIPTIONS.get(tool, "")
+            lines.append(f"- `{tool.value}`: {desc}")
 
         lines.append("")  # Empty line after each section