Address review: repr rejected-argument names, guard the completion result, add call_fn

- Log rejected tool arguments with %r: pydantic's error locations can
  include caller-supplied dict keys, which must not break onto new log
  lines.
- Build CompleteResult inside the completion adapter's try, so a handler
  returning the wrong type is logged as a crash and answered with the
  generic -32603 rather than "Invalid request parameters".
- On the legacy resolver path, a malformed ElicitResult from a
  non-conformant client no longer has its pydantic text repeated back.
- Add FuncMetadata.call_fn() for calling with already-validated
  arguments and use it from Tool.run; call_fn_with_arg_validation()
  becomes a deprecated wrapper (MCPDeprecationWarning, removal in 3.0).
- Docstring and docs wording: MCPError carve-outs, nested crash message,
  ResourceError in the imports and resource paragraph, the exact
  MCPDeprecationWarning path a traceback prints.

Author: maxisbey

docs/deprecated.md

@@ -123,7 +123,7 @@ That is the whole API. There is no per-method switch, and you don't want one: th
     `Error executing tool old_log`, and the captured server log names the culprit:
 
     ```text
-    mcp.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
+    mcp.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
     ```
 
     One line of pytest configuration, and a deprecated call can never sneak back into your

docs/servers/handling-errors.md

@@ -125,7 +125,7 @@ When it can't, raise `ResourceNotFoundError`. The SDK turns it into the protocol
 }
 ```
 
-Notice there is no `is_error=True` half-result here. A resource read either returns contents or fails: resources have only the protocol path. `ResourceError` is the same thing for a failure that isn't "not found" (`-32603`, your message). Any other exception is a crash: the client gets `-32603` naming only the URI, and the traceback goes to your log at `ERROR`. Templates and everything else about resources live in **[Resources](resources.md)**.
+Notice there is no `is_error=True` half-result here. A resource read either returns contents or fails: resources have only the protocol path. `ResourceError` is the same thing for a failure that isn't "not found" (`-32603`, your message), and both are one `INFO` line in your log. Any other exception bar `MCPError` is a crash: the client gets `-32603` naming only the URI, and the traceback goes to your log at `ERROR`. Templates and everything else about resources live in **[Resources](resources.md)**.
 
 ## Errors you never raise
 
@@ -136,8 +136,8 @@ Send `get_author` a `title` that isn't a string and the SDK rejects it against t
 It means a whole class of `raise` statements you don't write: don't re-validate your own type hints.
 
 !!! info
-    Everything on this page is what a **client** sees, and the in-memory `Client` you'll write
-    tests with sees exactly the same thing. Even `raise_exceptions=True` doesn't hand a failing
+    Everything a **client** sees on this page, the in-memory `Client` you'll write tests with
+    sees too. Even `raise_exceptions=True` doesn't hand a failing
     tool's exception back to the caller: by the time that flag could act, your exception is already
     the `is_error=True` result. Assert on the result. If you need the traceback of a crash, it is in
     the server's log, and pytest's `caplog` captures it. **[Testing](../get-started/testing.md)** covers the pattern.
@@ -150,7 +150,7 @@ It means a whole class of `raise` statements you don't write: don't re-validate
 * Any **other exception** is a crash -> `is_error=True` with only `Error executing tool <name>` for the model, and an `ERROR` record with the traceback for you.
 * `ResourceNotFoundError` from a resource handler -> the protocol's `-32602`, with the URI in `data`.
 * Bad arguments are rejected against the schema before your function runs; you don't `raise` for those.
-* Imports: `from mcp import MCPError`, `from mcp.server.mcpserver.exceptions import ToolError, ResourceNotFoundError`, and the error-code constants from `mcp.types`.
+* Imports: `from mcp import MCPError`, `from mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError`, and the error-code constants from `mcp.types`.
 
 Errors handled. That is everything a server *exposes*. What every handler can read, and do back to the client while it runs, is the next section: **[Inside your handler](../handlers/index.md)**.
 

docs/troubleshooting.md

@@ -92,7 +92,7 @@ result.structured_content  # None
 
 The fix is in your client: **check `result.is_error`**. A `try/except` around `call_tool` catches none of these, because there is nothing to catch. This is deliberate, and it is the single most useful thing on this page to internalise: the *model* chose the call, so the model gets the message and a chance to try again. **[Handling errors](servers/handling-errors.md)** is the whole story, including the `MCPError` path that *does* raise.
 
-The bare form, `Error executing tool <name>` with no message, means the tool **crashed**: it raised something other than `ToolError`, and the exception's text is kept off the wire. The traceback is in the **server's log** at `ERROR`, as `Tool '<name>' raised an unexpected exception`.
+The bare form, `Error executing tool <name>` with no message, means the tool **crashed**: something other than `ToolError` was raised while running it (or its return value failed the output schema), and that exception's text is kept off the wire. The traceback is in the **server's log** at `ERROR`, as `Tool '<name>' raised an unexpected exception`.
 
 ## `TypeError: The @tool decorator was used incorrectly. Did you forget to call it? Use @tool() instead of @tool`
 

src/mcp/server/mcpserver/exceptions.py

@@ -46,9 +46,10 @@ class ToolError(MCPServerError):
     Raise this from a tool (or a resolver) for a failure you saw coming: the
     call returns `is_error=True` with your message in `content` for the model to
     read, and the server logs it at INFO without a traceback. Any other exception
-    is treated as a crash: the model sees only `Error executing tool <name>`, and
-    the server logs the traceback at ERROR. A `ResourceError` that escapes the tool
-    (say from `ctx.read_resource()`) counts as anticipated too.
+    (bar `MCPError`, which is a protocol error) is treated as a crash: the model
+    sees only `Error executing tool <name>`, and the server logs the traceback at
+    ERROR. A `ResourceError` that escapes the tool (say from `ctx.read_resource()`)
+    counts as anticipated too.
 
     The SDK raises it too, for an unknown tool name and for arguments that fail
     the input schema, and `UnexpectedToolError` subclasses it, so `except ToolError`
@@ -61,8 +62,9 @@ class UnexpectedToolError(ToolError):
 
     The SDK raises this itself, around a crash in the tool (or a resolver) or a
     return value that fails output conversion. You never raise it. The message is
-    only `Error executing tool <name>`, so nothing from the original reaches the
-    client. `__cause__` is the original exception, which the server logs with its
+    only `Error executing tool <name>` (followed by the same for a nested tool or
+    resource that crashed), so nothing from the original reaches the client.
+    `__cause__` is the original exception, which the server logs with its
     traceback before returning the `is_error=True` result. Catch it around
     `MCPServer.call_tool()` to tell a crash from a deliberate `ToolError`.
     """

src/mcp/server/mcpserver/resolve.py

@@ -580,7 +580,10 @@ async def _fulfil(marker: _Marker, key: str, res: _Resolution) -> ElicitationRes
             except ValueError as e:
                 # Accepted with no content, or content that fails the schema: the same
                 # client mistake the input_required path below reports as a ToolError.
-                raise ToolError(f"Resolver {key!r}: {e}") from e
+                # (A pydantic ValidationError here means a non-conformant client sent a
+                # malformed ElicitResult; its text is not repeated back.)
+                detail = "received an invalid elicitation response" if isinstance(e, ValidationError) else str(e)
+                raise ToolError(f"Resolver {key!r}: {detail}") from e
         result = await res.context.session.send_request(
             _render_request(marker),
             _result_type(marker),

src/mcp/server/mcpserver/server.py

@@ -431,7 +431,7 @@ async def _handle_call_tool(
                 if isinstance(exc.__cause__, ValidationError):
                     # Field names only: the rejected values are the caller's data.
                     fields = sorted({".".join(str(part) for part in err["loc"]) for err in exc.__cause__.errors()})
-                    logger.info("Tool %r rejected arguments: %s", params.name, ", ".join(fields))
+                    logger.info("Tool %r rejected arguments: %r", params.name, fields)
                 else:
                     # %r keeps peer-supplied text on one line.
                     logger.info("Tool %r failed: %r", params.name, str(exc))
@@ -521,10 +521,10 @@ async def call_tool(
 
         Raises:
             ToolError: If the tool is unknown, the arguments fail validation, or the
-                tool (or a resolver) raises `ToolError`.
-            UnexpectedToolError: If the tool (or a resolver) raises anything other than
-                `ToolError` or `MCPError`, or its return value fails output conversion.
-                `__cause__` is the original exception.
+                tool (or a resolver) raises `ToolError` or `ResourceError`.
+            UnexpectedToolError: If the tool (or a resolver) raises anything else, or
+                its return value fails output conversion. `__cause__` is the original
+                exception.
         """
         if context is None:
             context = Context(mcp_server=self, subscriptions=self._subscriptions)
@@ -740,16 +740,16 @@ async def handler(
             ) -> CompleteResult:
                 try:
                     result = await func(params.ref, params.argument, params.context)
+                    return CompleteResult(
+                        completion=result if result is not None else Completion(values=[], total=None, has_more=None),
+                    )
                 except MCPError:
                     raise
                 except Exception as exc:
                     logger.exception("Completion for argument %r raised an unexpected exception", params.argument.name)
                     raise MCPError(
                         code=INTERNAL_ERROR, message=f"Error completing argument {params.argument.name}"
                     ) from exc
-                return CompleteResult(
-                    completion=result if result is not None else Completion(values=[], total=None, has_more=None),
-                )
 
             self._lowlevel_server.add_request_handler("completion/complete", CompleteRequestParams, handler)
             return func

src/mcp/server/mcpserver/tools/base.py

@@ -173,13 +173,7 @@ async def run(
                     return self.fn_metadata.convert_result(resolved) if convert_result else resolved
                 pass_directly |= resolved
 
-            result = await self.fn_metadata.call_fn_with_arg_validation(
-                self.fn,
-                self.is_async,
-                arguments,
-                pass_directly or None,
-                pre_validated=validated,
-            )
+            result = await self.fn_metadata.call_fn(self.fn, self.is_async, validated, pass_directly)
 
             # Registration rejects the annotated form of this combination; this covers
             # a body that returns an InputRequiredResult without declaring it. It is

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -23,7 +23,7 @@
 )
 from pydantic.fields import FieldInfo
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaWarningKind
-from typing_extensions import NotRequired, ReadOnly, TypedDict, get_type_hints, is_typeddict
+from typing_extensions import NotRequired, ReadOnly, TypedDict, deprecated, get_type_hints, is_typeddict
 from typing_inspection.introspection import (
     UNKNOWN,
     AnnotationSource,
@@ -35,6 +35,7 @@
 from mcp.server.mcpserver.exceptions import InvalidSignature
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.server.mcpserver.utilities.types import Audio, Image
+from mcp.shared.exceptions import MCPDeprecationWarning
 
 logger = get_logger(__name__)
 
@@ -125,6 +126,28 @@ def validate_arguments(self, arguments_to_validate: dict[str, Any]) -> dict[str,
         arguments_parsed_model = self.arg_model.model_validate(arguments_pre_parsed)
         return arguments_parsed_model.model_dump_one_level()
 
+    async def call_fn(
+        self,
+        fn: Callable[..., Any | Awaitable[Any]],
+        fn_is_async: bool,
+        arguments: dict[str, Any],
+        arguments_to_pass_directly: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call the function with already-validated `arguments` plus `arguments_to_pass_directly`.
+
+        `arguments` is the output of `validate_arguments`. A sync function runs on a
+        worker thread.
+        """
+        kwargs = arguments | (arguments_to_pass_directly or {})
+        if fn_is_async:
+            return await fn(**kwargs)
+        return await anyio.to_thread.run_sync(functools.partial(fn, **kwargs))
+
+    @deprecated(
+        "FuncMetadata.call_fn_with_arg_validation() is deprecated and will be removed in 3.0; "
+        "call validate_arguments() and then call_fn() instead.",
+        category=MCPDeprecationWarning,
+    )
     async def call_fn_with_arg_validation(
         self,
         fn: Callable[..., Any | Awaitable[Any]],
@@ -133,25 +156,12 @@ async def call_fn_with_arg_validation(
         arguments_to_pass_directly: dict[str, Any] | None,
         pre_validated: dict[str, Any] | None = None,
     ) -> Any:
-        """Call the given function with arguments validated and injected.
+        """Validate `arguments_to_validate` (unless `pre_validated` is given) and call the function.
 
-        Arguments are first attempted to be parsed from JSON, then validated against
-        the argument model, before being passed to the function. Pass `pre_validated`
-        (the output of `validate_arguments`) to reuse an earlier validation pass -
-        validating twice can re-run `default_factory`/stateful validators and hand the
-        function different values than a caller already observed.
+        Deprecated: call `validate_arguments` and then `call_fn`.
         """
-        # Copy so a caller-provided `pre_validated` dict is never mutated in place.
-        arguments_parsed_dict = dict(
-            pre_validated if pre_validated is not None else self.validate_arguments(arguments_to_validate)
-        )
-
-        arguments_parsed_dict |= arguments_to_pass_directly or {}
-
-        if fn_is_async:
-            return await fn(**arguments_parsed_dict)
-        else:
-            return await anyio.to_thread.run_sync(functools.partial(fn, **arguments_parsed_dict))
+        arguments = pre_validated if pre_validated is not None else self.validate_arguments(arguments_to_validate)
+        return await self.call_fn(fn, fn_is_async, arguments, arguments_to_pass_directly)
 
     def convert_result(self, result: Any) -> CallToolResult | InputRequiredResult:
         """Convert a function call result into a `CallToolResult`.