@@ -65,7 +65,6 @@ def _load_cursor_mcp_config(config_path: Optional[Path] = None) -> Optional[dict
 
 
 def _cursor_mcp_config_paths(workspace_roots: object) -> list[Path]:
-    """The MCP configs a Cursor session may load servers from: each project's, then the user's."""
     roots = workspace_roots if isinstance(workspace_roots, list) else []
     paths = [Path(root) / _REPO_SUBDIR / _MCP_CONFIG_FILENAME for root in roots if isinstance(root, str) and root]
     paths.append(_cursor_mcp_config_path())
@@ -81,13 +80,7 @@ def _server_command_line(server: dict) -> Optional[str]:
 
 
 def _resolve_mcp_server_name(raw_payload: dict) -> Optional[str]:
-    """The ``mcp.json`` entry name of the server a beforeMCPExecution payload called.
-
-    Cursor identifies the server by its ``url`` (remote servers) or ``command`` (stdio servers)
-    rather than by the entry name the platform stores servers under, so look the entry up in the
-    MCP configs: a url matches exactly; a command matches the entry's command line (command + args),
-    or the entry name itself. Falls back to the raw ``command`` when no entry matches.
-    """
+    """Cursor sends the server's url or command, but the platform knows it by its mcp.json entry name."""
     url = raw_payload.get('url')
     command = raw_payload.get('command')
     if not url and not command:
 
@@ -38,8 +38,7 @@
     )
 )
 
-# Guardrails that are Off unless the platform switches them on for an agent. The rest default to
-# Report; these would otherwise start enforcing on a tenant that never looked at them.
+# Off by default (not Report), so they never start enforcing on a tenant that hasn't configured them.
 _DEFAULT_OFF_GUARDRAIL_KEYS = frozenset((BlockReason.UNAUTHORIZED_MCP_SERVER.value,))
 
 
@@ -48,7 +47,6 @@ def get_config_cache_path() -> Path:
 
 
 def default_mode_for(guardrail_key: str) -> str:
-    """A guardrail's mode for an agent the platform sent no cell for (or with no cache at all)."""
     if guardrail_key in _DEFAULT_OFF_GUARDRAIL_KEYS:
         return GuardrailCellMode.OFF.value
     return GuardrailCellMode.REPORT.value
@@ -78,7 +76,6 @@ def mode_for(self, guardrail_key: str, ide_name: Optional[str]) -> str:
         return str(agents.get((ide_name or '').lower(), default_mode_for(guardrail_key))).lower()
 
     def is_off_for_every_agent(self, guardrail_key: str) -> bool:
-        """No agent has this guardrail on - nothing it needs has to be fetched."""
         agents = (self._guardrails.get(guardrail_key) or {}).get('agents') or {}
         return all(str(mode).lower() == GuardrailCellMode.OFF for mode in agents.values())
 
@@ -116,10 +113,9 @@ def apply_platform_config(policy: dict, config: Optional[GuardrailConfig], ide_n
     """Overlay the platform-owned enforcement config onto the local knobs-only policy.
 
     The platform is the only mode source: no cache (cold start) means the built-in defaults -
-    Report everywhere with the default globs, the unauthorized MCP server guardrail Off - which
-    equal an unconfigured tenant's platform config, so behaviour is uniform either way. Each matrix
-    cell lands on its own per-feature action, so the guardrails sharing an event (FileRead: content
-    scan vs. sensitive path; McpExecution: argument scan vs. server authorization) keep independent modes.
+    Report everywhere (unauthorized MCP server Off) with the default globs - which equal an unconfigured
+    tenant's platform config, so behaviour is uniform either way. Each matrix cell lands on its own
+    per-feature action, so guardrails sharing an event (e.g. the two FileRead ones) keep independent modes.
     An all-Off event never reaches here at all: scan_command skips it.
     """
 
 
@@ -223,7 +223,7 @@ class _ArgScanFeature:
 
 
 class _PreScanFinding(NamedTuple):
-    """A guardrail that fired on the call itself, before its text is scanned (e.g. an unauthorized MCP server)."""
+    """A finding on the call itself (e.g. an unauthorized MCP server), made before the text scan."""
 
     block_reason: BlockReason
     mode: GuardrailsMode
@@ -241,9 +241,7 @@ def _handle_arg_scan(
 ) -> HookDecision:
     """Shared scan + decision flow for MCP_EXECUTION and COMMAND_EXEC events.
 
-    A pre-scan finding in Block mode denies without scanning. In Report mode it marks the event
-    warned and the scan still runs; a secret the scan then finds takes over the response and the
-    event's block reason and outcome, since that is what the user is shown.
+    A Report-mode pre-scan finding still scans, and a secret found then takes over the response.
     """
     ai_client = ctx.obj['ai_security_client']
 
@@ -313,10 +311,7 @@ def _handle_arg_scan(
 
 
 def _check_mcp_server_authorization(payload: AIHookPayload, policy: dict) -> Optional[_PreScanFinding]:
-    """The unauthorized MCP server guardrail: a finding when the called server is enforced, else None.
-
-    Fails open - no server name, or no cached statuses, means the server is let through.
-    """
+    """Fails open: no server name or no cached statuses lets the call through."""
     mcp_config = get_policy_value(policy, 'mcp', default={})
     if not get_policy_value(mcp_config, 'check_server', default=False):
         return None
@@ -333,7 +328,7 @@ def _check_mcp_server_authorization(payload: AIHookPayload, policy: dict) -> Opt
 
     server = statuses.match(alias)
     if server is not None and server.alias.lower() != alias.lower():
-        # A normalized or plugin-namespaced name: report the alias the platform resolves servers by.
+        # Report the alias the platform stores, not the normalized or plugin-namespaced one.
         payload.mcp_server_name = server.alias
 
     status = server.status if server is not None else None
@@ -361,7 +356,7 @@ def _check_mcp_server_authorization(payload: AIHookPayload, policy: dict) -> Opt
 
 
 def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, policy: dict) -> HookDecision:
-    """Check the MCP server is authorized, then scan the tool arguments for secrets before execution."""
+    """Check the MCP server is authorized, then scan the tool arguments for secrets."""
     tool = payload.mcp_tool_name or 'unknown'
     args = payload.mcp_arguments or {}
     args_text = args if isinstance(args, str) else json.dumps(args)
 
@@ -1,10 +1,6 @@
-"""MCP server authorization status cache, for the unauthorized MCP server guardrail.
+"""MCP server authorization status cache: session-start writes it, the pre-MCP-execution hook reads it.
 
-session-start fetches the authorization status of every MCP server the platform ingested from
-this user's devices (Inventory -> AI Governance) and writes it here; the pre-MCP-execution hook
-only reads it. An absent or corrupt cache means no status is known, so the guardrail fails open.
-The cache also keeps the "Unauthorized AI Entity" policy's strict-mode flag the platform returns
-with the statuses (whether unreviewed servers count as unauthorized).
+An absent or corrupt cache means no status is known, so the guardrail fails open.
 """
 
 import json
@@ -24,11 +20,9 @@
 
 MCP_SERVER_STATUSES_FILE_NAME = 'ai-guardrails-mcp-servers.json'
 
-# The platform's response field for the strict mode, kept under the same name in the cache.
 TREAT_UNREVIEWED_AS_UNAUTHORIZED_KEY = 'should_treat_unreviewed_as_unauthorized'
 
-# Claude Code namespaces a plugin's servers in tool names as `plugin_<plugin>_<server>`, while the
-# platform stores the server under its config key - the name the session sweep reported.
+# Claude Code names plugin servers `plugin_<plugin>_<server>` in tool names; the platform stores `<server>`.
 _PLUGIN_ALIAS_PREFIX = 'plugin_'
 
 
@@ -38,8 +32,7 @@ class McpServerAuthorizationStatus(str, Enum):
     UNAUTHORIZED = 'Unauthorized'
 
 
-# When one alias maps to several servers (e.g. the same name configured differently on two
-# devices), the most restrictive status wins.
+# An alias shared by several servers (e.g. configured differently per device) gets the most restrictive status.
 _RESTRICTIVENESS = {
     McpServerAuthorizationStatus.AUTHORIZED: 0,
     McpServerAuthorizationStatus.UNREVIEWED: 1,
@@ -52,7 +45,7 @@ def get_mcp_server_statuses_cache_path() -> Path:
 
 
 def parse_status(raw_status: object) -> McpServerAuthorizationStatus:
-    """Case-insensitive; an unknown status reads as Unreviewed (no decision was made on the server)."""
+    """An unknown status reads as Unreviewed: no decision was made on the server."""
     lowered = str(raw_status or '').lower()
     for status in McpServerAuthorizationStatus:
         if status.value.lower() == lowered:
@@ -61,16 +54,12 @@ def parse_status(raw_status: object) -> McpServerAuthorizationStatus:
 
 
 def _normalize_alias(alias: str) -> str:
-    """The form an IDE may turn a config name into inside a tool name (Claude Code keeps [A-Za-z0-9_-])."""
+    """Mirrors how Claude Code sanitizes a config name inside a tool name."""
     return re.sub(r'[^a-z0-9_-]', '_', alias.lower())
 
 
 def is_enforced(status: Optional[McpServerAuthorizationStatus], treat_unreviewed: bool) -> bool:
-    """Whether a server with this status (None: the platform never saw it) is enforced.
-
-    Unauthorized always is; Unreviewed or unknown only when the policy treats unreviewed servers as
-    unauthorized (``treat_unreviewed``); Authorized never is.
-    """
+    """``status`` is None when the platform never saw the server."""
     if status == McpServerAuthorizationStatus.UNAUTHORIZED:
         return True
     return treat_unreviewed and status != McpServerAuthorizationStatus.AUTHORIZED
@@ -91,8 +80,7 @@ class McpServerStatuses:
     _by_alias: dict = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
-        # Lowered alias -> (stored alias, most restrictive status). The platform matches aliases
-        # case-insensitively, so the CLI does too.
+        # The platform matches aliases case-insensitively, so the CLI does too.
         self._by_alias = {}
         for server in self.servers:
             if not isinstance(server, dict) or not server.get('alias'):
@@ -104,7 +92,6 @@ def __post_init__(self) -> None:
                 self._by_alias[alias.lower()] = McpServerMatch(alias, status)
 
     def match(self, alias: str) -> Optional[McpServerMatch]:
-        """The platform's entry for the alias a hook reported, or None when the platform has none."""
         exact = self._by_alias.get(alias.lower())
         if exact is not None:
             return exact
@@ -127,7 +114,6 @@ def is_expired(self) -> bool:
         return time.time() - self.fetched_at > self.ttl_seconds
 
     def needs_refresh(self, tenant_id: Optional[str]) -> bool:
-        """Expired, or fetched for another tenant (the user switched tenants since)."""
         return self.is_expired() or self.tenant_id != tenant_id
 
 
@@ -137,7 +123,6 @@ def save_mcp_server_statuses(
     ttl_seconds: float = DEFAULT_TTL_SECONDS,
     treat_unreviewed_as_unauthorized: bool = False,
 ) -> None:
-    """Persist fetched statuses; a failed write just leaves the previous cache in place."""
     path = get_mcp_server_statuses_cache_path()
     content = {
         'fetched_at': time.time(),
@@ -154,7 +139,6 @@ def save_mcp_server_statuses(
 
 
 def load_mcp_server_statuses() -> Optional[McpServerStatuses]:
-    """The cached statuses, or None when the cache is absent or corrupt (quarantined)."""
     path = get_mcp_server_statuses_cache_path()
     if not path.exists():
         return None
@@ -170,7 +154,6 @@ def load_mcp_server_statuses() -> Optional[McpServerStatuses]:
             fetched_at=float(content['fetched_at']),
             tenant_id=content.get('tenant_id'),
             ttl_seconds=float(content.get('ttl_seconds') or DEFAULT_TTL_SECONDS),
-            # Missing in caches written before the flag existed: not strict.
             treat_unreviewed_as_unauthorized=content.get(TREAT_UNREVIEWED_AS_UNAUTHORIZED_KEY) is True,
         )
     except Exception as e:
 
@@ -92,7 +92,7 @@ def _report_session_context(
 
     The device context is always reported. MCP configs and skills are collected from every
     registered IDE, not just the triggering one. Unchanged payloads are skipped via a hash cache
-    until the TTL expires. Returns whether a report was accepted in this call.
+    until the TTL expires.
     """
     try:
         config_files_by_ide, enabled_plugins = collect_all_session_contexts()
@@ -205,13 +205,7 @@ def _sync_guardrail_config(ai_client: 'AISecurityManagerClient', tenant_id: Opti
 
 
 def _sync_mcp_server_statuses(ai_client: 'AISecurityManagerClient', tenant_id: Optional[str], force: bool) -> None:
-    """Refresh the MCP server authorization statuses the unauthorized MCP server guardrail reads.
-
-    Fetched only while the guardrail is on for some agent. Refreshed when the cache is expired or
-    belongs to another tenant, and whenever a changed session context was just reported (``force``):
-    that report may have brought servers the cached statuses don't cover yet. A failed fetch keeps
-    the previous cache.
-    """
+    """``force``: a just-reported session context may have brought servers the cache doesn't cover."""
     config = load_guardrail_config()
     if config is None or config.is_off_for_every_agent(BlockReason.UNAUTHORIZED_MCP_SERVER):
         logger.debug('Unauthorized MCP server guardrail is off, skipping MCP server statuses fetch')
 
@@ -15,7 +15,7 @@
 
 class McpServerStatusesResponse(NamedTuple):
     servers: list  # [{alias, normalized_id, status}]
-    # The "Unauthorized AI Entity" policy's strict mode: Unreviewed servers count as Unauthorized.
+    # Strict mode: Unreviewed servers count as Unauthorized.
     should_treat_unreviewed_as_unauthorized: bool
 
 
@@ -94,8 +94,7 @@ def create_event(
             'mcp_tool_name': payload.mcp_tool_name,
             'error_message': error_message,
             'file_path': file_path,
-            # The device the hook ran on, so a guardrail violation lands on it rather than on any of
-            # the user's devices. None where no serial can be resolved (e.g. Linux).
+            # Attributes a violation to this device; None where no serial resolves (e.g. Linux).
             'device_id': get_serial_number(),
         }
 
@@ -115,11 +114,6 @@ def get_resolved_guardrails(self) -> Optional[dict]:
             return None
 
     def get_mcp_server_statuses(self) -> Optional[McpServerStatusesResponse]:
-        """Fetch the authorization status of every MCP server on the caller's devices.
-
-        Returns the server rows with the policy's strict-mode flag (missing or non-boolean reads as
-        False), or None when the fetch failed.
-        """
         try:
             response = self.client.get(self._build_endpoint_path(self._MCP_SERVER_STATUSES_PATH))
             body = response.json()
 
@@ -12,10 +12,7 @@ def resolved_guardrails_payload(
     globs: Optional[list] = None,
     mcp_server: Optional[str] = None,
 ) -> dict:
-    """A platform resolved-config payload with the given per-guardrail modes for the cursor agent.
-
-    The unauthorized MCP server guardrail is only in the payload when ``mcp_server`` is given.
-    """
+    """A platform resolved-config payload with the given per-guardrail modes for the cursor agent."""
     payload = {
         'ttl_seconds': 900,
         'guardrails': [
 
@@ -785,7 +785,7 @@ def test_fresh_mcp_server_statuses_skip_the_fetch_unless_forced(
     _session_start_mod._sync_mcp_server_statuses(ai_client, 'tenant-b', force=False)
     assert ai_client.get_mcp_server_statuses.call_count == 1
 
-    # A just-reported session context may have brought new servers: refetch even when fresh.
+    # A just-reported session context forces a refetch.
     _session_start_mod._sync_mcp_server_statuses(ai_client, 'tenant-a', force=True)
     assert ai_client.get_mcp_server_statuses.call_count == 2
 
 
@@ -20,7 +20,7 @@ def _build_client() -> tuple[AISecurityManagerClient, MagicMock]:
 
 @pytest.fixture(autouse=True)
 def serial_number(mocker: MockerFixture) -> MagicMock:
-    """Resolving the real serial shells out and caches under the home directory."""
+    """Don't shell out for the real serial."""
     return mocker.patch('cycode.cyclient.ai_security_manager_client.get_serial_number', return_value='SERIAL-1')