Add ToolExecutionExceptionInterface for custom tool error handling

Author: MartkCz

src/Capability/Registry/ReferenceHandlerInterface.php

@@ -27,8 +27,9 @@ interface ReferenceHandlerInterface
      *
      * @return mixed the result of the element execution
      *
-     * @throws \Mcp\Exception\InvalidArgumentException if the handler is invalid
-     * @throws \Mcp\Exception\RegistryException        if execution fails
+     * @throws \Mcp\Exception\InvalidArgumentException        if the handler is invalid
+     * @throws \Mcp\Exception\ToolExecutionExceptionInterface if the tool reports an error during its execution
+     * @throws \Mcp\Exception\RegistryException               if execution fails
      */
     public function handle(ElementReference $reference, array $arguments): mixed;
 }

src/Capability/Tool/ToolCaller.php

@@ -14,6 +14,7 @@
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
 use Mcp\Exception\ToolCallException;
+use Mcp\Exception\ToolExecutionExceptionInterface;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Content\AudioContent;
 use Mcp\Schema\Content\EmbeddedResource;
@@ -68,6 +69,11 @@ public function call(CallToolRequest $request): CallToolResult
             ]);
 
             return new CallToolResult($formattedResult);
+        } catch (ToolExecutionExceptionInterface $e) {
+            return CallToolResult::error(array_map(
+                fn (string $message): TextContent => new TextContent($message),
+                $e->getErrorMessages(),
+            ));
         } catch (\Throwable $e) {
             $this->logger->error('Tool execution failed', [
                 'name' => $toolName,

src/Capability/Tool/ToolCallerInterface.php

@@ -12,6 +12,7 @@
 namespace Mcp\Capability\Tool;
 
 use Mcp\Exception\ToolCallException;
+use Mcp\Exception\ToolExecutionExceptionInterface;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
@@ -22,8 +23,9 @@
 interface ToolCallerInterface
 {
     /**
-     * @throws ToolCallException     if the tool execution fails
-     * @throws ToolNotFoundException if the tool is not found
+     * @throws ToolCallException               if the tool execution fails
+     * @throws ToolNotFoundException           if the tool is not found
+     * @throws ToolExecutionExceptionInterface if the tool reports an error during its execution
      */
     public function call(CallToolRequest $request): CallToolResult;
 }

src/Capability/ToolChain.php

@@ -17,6 +17,7 @@
 use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\InvalidCursorException;
 use Mcp\Exception\ToolCallException;
+use Mcp\Exception\ToolExecutionExceptionInterface;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
@@ -67,6 +68,10 @@ public function call(CallToolRequest $request): CallToolResult
                 try {
                     return $item->call($request);
                 } catch (\Throwable $e) {
+                    if ($e instanceof ToolExecutionExceptionInterface) {
+                        throw $e;
+                    }
+
                     throw new ToolCallException($request, $e);
                 }
             }

src/Exception/ToolExecutionExceptionInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Exception;
+
+interface ToolExecutionExceptionInterface extends \Throwable
+{
+    /**
+     * @return non-empty-list<non-empty-string>
+     */
+    public function getErrorMessages(): array;
+}

tests/Capability/Tool/ToolCallerTest.php

@@ -175,6 +175,38 @@ public function testCallThrowsToolNotFoundExceptionWhenToolNotFound(): void
         $this->toolCaller->call($request);
     }
 
+    public function testCallThrowsToolExecutionException(): void
+    {
+        $request = new CallToolRequest('test_tool', ['param' => 'value']);
+        $tool = $this->createValidTool('test_tool');
+        $exception = new class extends \Exception implements \Mcp\Exception\ToolExecutionExceptionInterface {
+            public function getErrorMessages(): array
+            {
+                return ['test error'];
+            }
+        };
+        $toolReference = new ToolReference($tool, fn () => throw $exception);
+
+        $this->referenceProvider
+            ->expects($this->once())
+            ->method('getTool')
+            ->with('test_tool')
+            ->willReturn($toolReference);
+
+        $this->referenceHandler
+            ->expects($this->once())
+            ->method('handle')
+            ->with($toolReference, ['param' => 'value'])
+            ->willThrowException($exception);
+
+        $result = $this->toolCaller->call($request);
+
+        $this->assertCount(1, $result->content);
+        $this->assertInstanceOf(TextContent::class, $result->content[0]);
+        $this->assertEquals('test error', $result->content[0]->text);
+        $this->assertTrue($result->isError);
+    }
+
     public function testCallThrowsToolExecutionExceptionWhenHandlerThrowsException(): void
     {
         $request = new CallToolRequest('failing_tool', ['param' => 'value']);