docs(modules): correct hosted MCP notes and guard stale note keys

AgentWorks is available on the hosted Falcon MCP, so drop its
self-hosted-only note and remove it from the overview summary.

Reword the discovery paragraph. The previous text said this server needs
no discovery step, which holds only by default: dynamic mode uses the
same pattern through falcon_search_tools, falcon_execute_tool, and
falcon_list_enabled_tools. Link that page and call out the falcon_
prefix so the two tool sets are not conflated.

Say "not available" rather than "not yet available" for the cloud
insights tools, matching their per-tool notes, link the module names in
the summary, and resolve module URLs through a helper so a slug change
cannot break them.

Add validate_hosted_mcp_notes. Both note dicts are keyed by name, so a
rename silently dropped the note and the docs freshness check could not
catch it, since regenerating drops the note from the committed page as
well. The generator now fails instead, with tests covering a stale
module key, a stale tool key, and a note missing from the summary.

Author: carlosmmatos-cs

docs/modules/agentworks.md

@@ -6,9 +6,6 @@
 
 Calling, listing, and observing CrowdStrike AgentWorks (agentic-studio) Charlotte AI agents and their execution traces
 
-> [!NOTE]
-> This module is not available on CrowdStrike's hosted Falcon MCP; it is only available when self-hosting this server. See [module overview](/falcon-mcp/modules/overview/#crowdstrike-hosted-mcp-differences).
-
 ## API Scopes
 
 - `Charlotte AI Agent Definition:read`

docs/modules/overview.md

@@ -39,13 +39,15 @@ The Falcon MCP Server provides the following modules. Each module requires speci
 ## CrowdStrike-hosted MCP differences
 
 > [!NOTE]
-> This section compares this self-hosted server against CrowdStrike's hosted Falcon MCP. It does not apply if you're only running this server yourself.
+> This section compares this self-hosted server against CrowdStrike's hosted Falcon MCP. Skip it unless you also use the hosted MCP, or are moving between the two.
 
-The hosted Falcon MCP does not register each `falcon_*` tool directly. Instead it exposes two tools, `search_tools` and `execute_tool`: a client calls `search_tools` to find the right Falcon tool by name or keyword, then `execute_tool` to invoke it by name with arguments. This server registers every `falcon_*` tool (and its `falcon://` resources) directly, so no discovery step is needed.
+The two servers differ in how a client reaches a tool. The hosted Falcon MCP works through discovery: a client calls `search_tools` to find a Falcon tool by name or keyword, then `execute_tool` to run it with arguments. This server registers each `falcon_*` tool up front instead, so a client calls one by name with no discovery round-trip.
+
+If you self-host and want the same discovery pattern, enable [dynamic mode](/falcon-mcp/usage/dynamic-mode/): it swaps the full tool surface for `falcon_search_tools`, `falcon_execute_tool`, and an always-on `falcon_list_enabled_tools` inventory. Mind the `falcon_` prefix — those three are this server's tools, not the hosted MCP's.
 
 Module and tool coverage also differs:
 
-- **AgentWorks**, **Fusion SOAR**, and **Zero Trust Assessment** are available only on this self-hosted server; the hosted MCP has no equivalent modules.
-- [Cloud Security](/falcon-mcp/modules/cloud/): `falcon_search_cloud_insights`, `falcon_list_cloud_insight_definitions`, and `falcon_get_cloud_asset_insights` are not yet available on the hosted MCP.
+- [Fusion SOAR](/falcon-mcp/modules/fusion/) and [Zero Trust Assessment](/falcon-mcp/modules/zero-trust-assessment/) are available only on this self-hosted server; the hosted MCP has no equivalent modules.
+- [Cloud Security](/falcon-mcp/modules/cloud/): `falcon_search_cloud_insights`, `falcon_list_cloud_insight_definitions`, and `falcon_get_cloud_asset_insights` are not available on the hosted MCP.
 - [Discover](/falcon-mcp/modules/discover/): `falcon_search_managed_assets` is not available on the hosted MCP.
 - [Policies](/falcon-mcp/modules/policies/): the hosted MCP does not use the unified `policy_type`-discriminated tools. It instead exposes six policy-type-specific variants of each tool (for example `falcon_search_policies_firewall`, `falcon_create_policy_prevention`).

scripts/generate_module_docs.py

@@ -77,14 +77,17 @@
 
 _OVERVIEW_LINK = f"{SITE_BASE_PATH}/modules/overview/#crowdstrike-hosted-mcp-differences"
 
+
+def _module_link(module_key: str) -> str:
+    """Site URL for a module page, honoring any slug override in MODULE_METADATA."""
+    slug = MODULE_METADATA.get(module_key, {}).get("slug", module_key)
+    return f"{SITE_BASE_PATH}/modules/{slug}/"
+
+
 # Notes on differences from CrowdStrike's hosted Falcon MCP, rendered as an
 # admonition under the module description. Keyed by module_key. See
 # generate_overview_page for the summary of these differences.
 HOSTED_MCP_MODULE_NOTES: dict[str, str] = {
-    "agentworks": (
-        "This module is not available on CrowdStrike's hosted Falcon MCP; it is only "
-        f"available when self-hosting this server. See [module overview]({_OVERVIEW_LINK})."
-    ),
     "fusion": (
         "This module is not available on CrowdStrike's hosted Falcon MCP; it is only "
         f"available when self-hosting this server. See [module overview]({_OVERVIEW_LINK})."
@@ -1432,34 +1435,43 @@ def generate_overview_page(modules: dict[str, dict[str, Any]]) -> str:
     lines.append("> [!NOTE]")
     lines.append(
         "> This section compares this self-hosted server against CrowdStrike's hosted "
-        "Falcon MCP. It does not apply if you're only running this server yourself."
+        "Falcon MCP. Skip it unless you also use the hosted MCP, or are moving between the two."
     )
     lines.append("")
     lines.append(
-        "The hosted Falcon MCP does not register each `falcon_*` tool directly. Instead it "
-        "exposes two tools, `search_tools` and `execute_tool`: a client calls `search_tools` "
-        "to find the right Falcon tool by name or keyword, then `execute_tool` to invoke it by "
-        "name with arguments. This server registers every `falcon_*` tool (and its `falcon://` "
-        "resources) directly, so no discovery step is needed."
+        "The two servers differ in how a client reaches a tool. The hosted Falcon MCP works "
+        "through discovery: a client calls `search_tools` to find a Falcon tool by name or "
+        "keyword, then `execute_tool` to run it with arguments. This server registers each "
+        "`falcon_*` tool up front instead, so a client calls one by name with no discovery "
+        "round-trip."
+    )
+    lines.append("")
+    lines.append(
+        "If you self-host and want the same discovery pattern, enable "
+        f"[dynamic mode]({SITE_BASE_PATH}/usage/dynamic-mode/): it swaps the full tool surface "
+        "for `falcon_search_tools`, `falcon_execute_tool`, and an always-on "
+        "`falcon_list_enabled_tools` inventory. Mind the `falcon_` prefix — those three are "
+        "this server's tools, not the hosted MCP's."
     )
     lines.append("")
     lines.append("Module and tool coverage also differs:")
     lines.append("")
     lines.append(
-        "- **AgentWorks**, **Fusion SOAR**, and **Zero Trust Assessment** are available only "
+        f"- [Fusion SOAR]({_module_link('fusion')}) and "
+        f"[Zero Trust Assessment]({_module_link('zerotrustassessment')}) are available only "
         "on this self-hosted server; the hosted MCP has no equivalent modules."
     )
     lines.append(
-        f"- [Cloud Security]({SITE_BASE_PATH}/modules/cloud/): `falcon_search_cloud_insights`, "
+        f"- [Cloud Security]({_module_link('cloud')}): `falcon_search_cloud_insights`, "
         "`falcon_list_cloud_insight_definitions`, and `falcon_get_cloud_asset_insights` are not "
-        "yet available on the hosted MCP."
+        "available on the hosted MCP."
     )
     lines.append(
-        f"- [Discover]({SITE_BASE_PATH}/modules/discover/): `falcon_search_managed_assets` is "
+        f"- [Discover]({_module_link('discover')}): `falcon_search_managed_assets` is "
         "not available on the hosted MCP."
     )
     lines.append(
-        f"- [Policies]({SITE_BASE_PATH}/modules/policies/): the hosted MCP does not use the "
+        f"- [Policies]({_module_link('policies')}): the hosted MCP does not use the "
         "unified `policy_type`-discriminated tools. It instead exposes six policy-type-specific "
         "variants of each tool (for example `falcon_search_policies_firewall`, "
         "`falcon_create_policy_prevention`)."
@@ -1468,13 +1480,47 @@ def generate_overview_page(modules: dict[str, dict[str, Any]]) -> str:
     return "\n".join(lines)
 
 
+def validate_hosted_mcp_notes(modules: dict[str, dict[str, Any]]) -> None:
+    """Fail loudly when a hosted-MCP note key matches no module or no registered tool.
+
+    Both note dicts are keyed by name, so a module or tool rename silently drops the
+    note: the page regenerates without it, the committed docs match, and the docs
+    freshness check passes. Raise here instead so a rename is caught at generation time.
+    """
+    stale_modules = sorted(set(HOSTED_MCP_MODULE_NOTES) - set(modules))
+
+    known_tools = {
+        f"falcon_{registered}"
+        for mod_info in modules.values()
+        for registered in extract_registered_tool_names(mod_info["cls"]).values()
+    }
+    stale_tools = sorted(set(HOSTED_MCP_TOOL_NOTES) - known_tools)
+
+    problems = []
+    if stale_modules:
+        problems.append(
+            f"HOSTED_MCP_MODULE_NOTES keys match no discovered module: {', '.join(stale_modules)}"
+        )
+    if stale_tools:
+        problems.append(
+            f"HOSTED_MCP_TOOL_NOTES keys match no registered tool: {', '.join(stale_tools)}"
+        )
+    if problems:
+        raise ValueError(
+            "Stale hosted-MCP note keys in scripts/generate_module_docs.py. "
+            "Update or remove them after a rename:\n  " + "\n  ".join(problems)
+        )
+
+
 def main() -> None:
     """Generate all module documentation pages."""
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
 
     modules = discover_module_classes()
     print(f"Discovered {len(modules)} modules: {', '.join(sorted(modules.keys()))}")
 
+    validate_hosted_mcp_notes(modules)
+
     # Generate overview page
     overview = generate_overview_page(modules)
     (OUTPUT_DIR / "overview.md").write_text(overview)

tests/test_generate_module_docs.py

@@ -29,6 +29,7 @@
     generate_module_page,
     generate_overview_page,
     main,
+    validate_hosted_mcp_notes,
 )
 
 # ---------------------------------------------------------------------------
@@ -1083,5 +1084,85 @@ def test_main_removes_stale_files(self):
             self.assertFalse(stale.exists(), "Stale file should have been removed by main()")
 
 
+# ---------------------------------------------------------------------------
+# TestHostedMcpNotes — note keys must track real module and tool names
+# ---------------------------------------------------------------------------
+
+class TestHostedMcpNotes(unittest.TestCase):
+    """Both hosted-MCP note dicts are keyed by name, so a rename silently drops the note.
+
+    The docs freshness check cannot catch that: regenerating after a rename removes the
+    note from the committed page too, so committed and generated agree. These tests are
+    the guard instead, mirroring the bidirectional coverage test for filter hints.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        cls.modules = discover_module_classes()
+        cls.tool_names = {
+            f"falcon_{registered}"
+            for mod_info in cls.modules.values()
+            for registered in extract_registered_tool_names(mod_info["cls"]).values()
+        }
+
+    def test_module_note_keys_are_real_modules(self):
+        from scripts.generate_module_docs import HOSTED_MCP_MODULE_NOTES
+
+        for key in HOSTED_MCP_MODULE_NOTES:
+            self.assertIn(key, self.modules, f"HOSTED_MCP_MODULE_NOTES key {key!r} is not a module")
+
+    def test_tool_note_keys_are_registered_tools(self):
+        from scripts.generate_module_docs import HOSTED_MCP_TOOL_NOTES
+
+        for name in HOSTED_MCP_TOOL_NOTES:
+            self.assertIn(
+                name, self.tool_names, f"HOSTED_MCP_TOOL_NOTES key {name!r} is not a registered tool"
+            )
+
+    def test_live_registry_passes_validation(self):
+        validate_hosted_mcp_notes(self.modules)  # must not raise
+
+    def test_stale_module_key_raises(self):
+        import scripts.generate_module_docs as _gmd
+
+        with patch.dict(_gmd.HOSTED_MCP_MODULE_NOTES, {"zero_trust_assessment": "x"}, clear=True):
+            with self.assertRaises(ValueError) as ctx:
+                validate_hosted_mcp_notes(self.modules)
+        self.assertIn("zero_trust_assessment", str(ctx.exception))
+
+    def test_stale_tool_key_raises(self):
+        import scripts.generate_module_docs as _gmd
+
+        with patch.dict(_gmd.HOSTED_MCP_TOOL_NOTES, {"falcon_search_cloud_insight": "x"}, clear=True):
+            with self.assertRaises(ValueError) as ctx:
+                validate_hosted_mcp_notes(self.modules)
+        self.assertIn("falcon_search_cloud_insight", str(ctx.exception))
+
+    def test_overview_mentions_every_noted_module_and_tool(self):
+        """The overview summary is hand-written prose; keep it in step with the note dicts."""
+        from scripts.generate_module_docs import (
+            HOSTED_MCP_MODULE_NOTES,
+            HOSTED_MCP_TOOL_NOTES,
+            MODULE_METADATA,
+        )
+
+        page = generate_overview_page(self.modules)
+        section = page.split("## CrowdStrike-hosted MCP differences", 1)[1]
+
+        for key in HOSTED_MCP_MODULE_NOTES:
+            slug = MODULE_METADATA.get(key, {}).get("slug", key)
+            self.assertIn(
+                f"/modules/{slug}/",
+                section,
+                f"Module {key!r} has a hosted-MCP note but is not linked in the overview summary",
+            )
+        for name in HOSTED_MCP_TOOL_NOTES:
+            self.assertIn(
+                name,
+                section,
+                f"Tool {name!r} has a hosted-MCP note but is not named in the overview summary",
+            )
+
+
 if __name__ == "__main__":
     unittest.main()