feature #224 [MCP SDK] Update Tool schema to match 2025-06-18 and introduce ToolAnnotationsInterface (xavierleune)

This PR was merged into the main branch.

Discussion
----------

[MCP SDK] Update Tool schema to match 2025-06-18 and introduce `ToolAnnotationsInterface`

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | no
| Issues        | --
| License       | MIT

The current Tool definition lacks a few fields, this PR covers it.

Commits
-------

98c3704 [MCP SDK] Update Tool schema to match 2025-06-18 and introduce ToolAnnotationsInterface

Author: chr-hertel

demo/src/MCP/Tools/CurrentTimeTool.php

@@ -12,6 +12,7 @@
 namespace App\MCP\Tools;
 
 use Symfony\AI\McpSdk\Capability\Tool\MetadataInterface;
+use Symfony\AI\McpSdk\Capability\Tool\ToolAnnotationsInterface;
 use Symfony\AI\McpSdk\Capability\Tool\ToolCall;
 use Symfony\AI\McpSdk\Capability\Tool\ToolCallResult;
 use Symfony\AI\McpSdk\Capability\Tool\ToolExecutorInterface;
@@ -54,4 +55,19 @@ public function getInputSchema(): array
             'required' => ['format'],
         ];
     }
+
+    public function getOutputSchema(): ?array
+    {
+        return null;
+    }
+
+    public function getTitle(): ?string
+    {
+        return null;
+    }
+
+    public function getAnnotations(): ?ToolAnnotationsInterface
+    {
+        return null;
+    }
 }

src/mcp-sdk/examples/cli/src/ExampleTool.php

@@ -12,6 +12,7 @@
 namespace App;
 
 use Symfony\AI\McpSdk\Capability\Tool\MetadataInterface;
+use Symfony\AI\McpSdk\Capability\Tool\ToolAnnotationsInterface;
 use Symfony\AI\McpSdk\Capability\Tool\ToolCall;
 use Symfony\AI\McpSdk\Capability\Tool\ToolCallResult;
 use Symfony\AI\McpSdk\Capability\Tool\ToolExecutorInterface;
@@ -51,4 +52,19 @@ public function getInputSchema(): array
             'required' => [],
         ];
     }
+
+    public function getOutputSchema(): ?array
+    {
+        return null;
+    }
+
+    public function getTitle(): ?string
+    {
+        return null;
+    }
+
+    public function getAnnotations(): ?ToolAnnotationsInterface
+    {
+        return null;
+    }
 }

src/mcp-sdk/src/Capability/Tool/IdentifierInterface.php

@@ -13,5 +13,8 @@
 
 interface IdentifierInterface
 {
+    /**
+     * @return string intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn’t present)
+     */
     public function getName(): string;
 }

src/mcp-sdk/src/Capability/Tool/MetadataInterface.php

@@ -11,19 +11,64 @@
 
 namespace Symfony\AI\McpSdk\Capability\Tool;
 
+/**
+ * @see {https://modelcontextprotocol.io/specification/2025-06-18/schema#tool}
+ */
 interface MetadataInterface extends IdentifierInterface
 {
-    public function getDescription(): string;
+    /**
+     * @return string|null A human-readable description of the tool.
+     *                     This can be used by clients to improve the LLM’s understanding of available tools. It can be thought of like a “hint” to the model
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#tool-description
+     */
+    public function getDescription(): ?string;
 
     /**
      * @return array{
-     *   type?: string,
+     *   type?: 'object',
      *   required?: list<string>,
      *   properties?: array<string, array{
      *       type: string,
      *       description?: string,
      *   }>,
      * }
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#tool-inputschema
      */
     public function getInputSchema(): array;
+
+    /**
+     * @return array{
+     *   type?: 'object',
+     *   required?: list<string>,
+     *   properties?: array<string, array{
+     *       type: string,
+     *       description?: string,
+     *   }>,
+     * }|null
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#tool-outputschema
+     */
+    public function getOutputSchema(): ?array;
+
+    /**
+     * @return string|null Intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology.
+     *
+     * If not provided, the name should be used for display (except for Tool, where annotations.title should be given precedence over using name, if present).
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#tool-title
+     */
+    public function getTitle(): ?string;
+
+    /**
+     * @return ToolAnnotationsInterface|null Additional properties describing a Tool to clients.
+     *
+     * NOTE: all properties in ToolAnnotations are hints. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like title).
+     *
+     * Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#tool-annotations
+     */
+    public function getAnnotations(): ?ToolAnnotationsInterface;
 }

src/mcp-sdk/src/Capability/Tool/ToolAnnotationsInterface.php

@@ -0,0 +1,62 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\McpSdk\Capability\Tool;
+
+interface ToolAnnotationsInterface
+{
+    /**
+     * @return bool|null If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates.
+     *
+     * (This property is meaningful only when readOnlyHint == false)
+     *
+     * Default: true
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-destructivehint
+     */
+    public function getDestructiveHint(): ?bool;
+
+    /**
+     * @return bool|null If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment.
+     *
+     * (This property is meaningful only when readOnlyHint == false)
+     *
+     * Default: false
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-idempotenthint
+     */
+    public function getIdempotentHint(): ?bool;
+
+    /**
+     * @return bool|null If true, this tool may interact with an “open world” of external entities. If false, the tool’s domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not.
+     *
+     * Default: true
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-openworldhint
+     */
+    public function getOpenWorldHint(): ?bool;
+
+    /**
+     * @return bool|null If true, the tool does not modify its environment.
+     *
+     * Default: false
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint
+     */
+    public function getReadOnlyHint(): ?bool;
+
+    /**
+     * @return string|null A human-readable title for the tool
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-title
+     */
+    public function getTitle(): ?string;
+}

src/mcp-sdk/src/Server/RequestHandler/ToolListHandler.php

@@ -36,14 +36,25 @@ public function createResponse(Request $message): Response
         foreach ($metadataList as $tool) {
             $nextCursor = $tool->getName();
             $inputSchema = $tool->getInputSchema();
-            $tools[] = [
+            $annotations = null === $tool->getAnnotations() ? [] : array_filter([
+                'title' => $tool->getAnnotations()->getTitle(),
+                'destructiveHint' => $tool->getAnnotations()->getDestructiveHint(),
+                'idempotentHint' => $tool->getAnnotations()->getIdempotentHint(),
+                'openWorldHint' => $tool->getAnnotations()->getOpenWorldHint(),
+                'readOnlyHint' => $tool->getAnnotations()->getReadOnlyHint(),
+            ], static fn ($value) => null !== $value);
+
+            $tools[] = array_filter([
                 'name' => $tool->getName(),
                 'description' => $tool->getDescription(),
                 'inputSchema' => [] === $inputSchema ? [
                     'type' => 'object',
                     '$schema' => 'http://json-schema.org/draft-07/schema#',
                 ] : $inputSchema,
-            ];
+                'title' => $tool->getTitle(),
+                'outputSchema' => $tool->getOutputSchema(),
+                'annotations' => (object) $annotations,
+            ], static fn ($value) => null !== $value);
         }
 
         $result = [

src/mcp-sdk/tests/Server/RequestHandler/ToolListHandlerTest.php

@@ -17,6 +17,7 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\AI\McpSdk\Capability\Tool\CollectionInterface;
 use Symfony\AI\McpSdk\Capability\Tool\MetadataInterface;
+use Symfony\AI\McpSdk\Capability\Tool\ToolAnnotationsInterface;
 use Symfony\AI\McpSdk\Message\Request;
 use Symfony\AI\McpSdk\Server\RequestHandler\ToolListHandler;
 
@@ -102,6 +103,21 @@ public function getInputSchema(): array
             {
                 return ['type' => 'object'];
             }
+
+            public function getOutputSchema(): ?array
+            {
+                return null;
+            }
+
+            public function getTitle(): string
+            {
+                return 'Test tool';
+            }
+
+            public function getAnnotations(): ?ToolAnnotationsInterface
+            {
+                return null;
+            }
         };
     }
 }