docs(tests): scope the failure-helper claim and fix safe_call_tool's docstring

Two corrections from Codex review:

call_tool_failure() only proves the call failed when expected_error is
given. assert_mcp_failure()'s check is `if data.get("success")`, so a
result dict that omits the key entirely is accepted as a failure. The
guidance now says to pass expected_error and states the limitation
rather than claiming the helper always proves failure.

safe_call_tool()'s own docstring still advertised it as the helper for
tests that expect a failure, contradicting the new rule in a second
place and recreating the ambiguity this branch removes. It now names its
real roles -- finally-block cleanup and availability probing -- and
points at call_tool_failure() for asserted failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c4gkE9mcKu4RiuQzR5eff

Author: kingpanther13

tests/AGENTS.md

@@ -49,10 +49,11 @@ rather than assume the e2e's always-present case.
 ## Test Patterns
 
 - Tests expecting tool **success**: use `mcp.call_tool_success()` inside `MCPAssertions` context
-- Tests expecting tool **failure**: use `mcp.call_tool_failure()` inside `MCPAssertions` context.
-  It catches the `ToolError`, asserts the call actually failed rather than silently
-  succeeding, and — when `expected_error` is given — matches it against the extracted
-  error message.
+- Tests expecting tool **failure**: use `mcp.call_tool_failure()` inside `MCPAssertions`
+  context, and **pass `expected_error`**. It catches the `ToolError` and matches
+  `expected_error` against the extracted message. Without `expected_error` it is a weak
+  assertion: the success check is `if data.get("success")`, so a result dict that omits
+  the key entirely is accepted as a failure.
 - `safe_call_tool()` is for calls whose outcome the test does **not** assert: `finally`
   cleanup (so a cleanup failure cannot mask the real assertion) and service-availability
   probes. It swallows `ToolError` and returns a parsed dict, so using it for an expected

tests/src/e2e/utilities/assertions.py

@@ -113,8 +113,11 @@ async def safe_call_tool(
 ) -> dict[str, Any]:
     """Call an MCP tool and return parsed result, handling ToolError exceptions.
 
-    This is useful for tests that expect tools to fail and want to inspect
-    the error response without catching exceptions manually.
+    For a call whose outcome the test does NOT assert: ``finally``-block cleanup
+    (so a cleanup failure cannot mask the real assertion) and service-availability
+    probes. It swallows ``ToolError`` and returns a parsed dict either way, so a
+    test that asserts a failure should use ``MCPAssertions.call_tool_failure()``
+    with ``expected_error`` instead -- see tests/AGENTS.md "Test Patterns".
 
     Args:
         mcp_client: The MCP client instance