feat(schema): add top-level title to Tool

Mirror PR modelcontextprotocol#278's Prompt change for Tool:

- Add optional ?string $title to Mcp\Schema\Tool between $name
  and $inputSchema. fromArray() now reads $data['title'];
  jsonSerialize() emits 'title' right after 'name'. The
  @phpstan-type ToolData gains title?: string.
- Add ?string $title to the #[McpTool] attribute between $name
  and $description.
- Note ToolAnnotations::$title as deprecated-for-display in
  favor of Tool::$title per MCP spec 2025-06-18 (PHPDoc only,
  field retained for BC).

Phase 1 of plan 01--tool-title-spec-compliance. Later phases
update Discoverer, Builder::addTool(), ArrayLoader, and the
conformance fixture to match the new signature.

Author: DDEV User

src/Capability/Attribute/McpTool.php

@@ -22,6 +22,7 @@ class McpTool
 {
     /**
      * @param string|null           $name         The name of the tool (defaults to the method name)
+     * @param string|null           $title        Optional human-readable title for display in UI
      * @param string|null           $description  The description of the tool (defaults to the DocBlock/inferred)
      * @param ToolAnnotations|null  $annotations  Optional annotations describing tool behavior
      * @param ?Icon[]               $icons        Optional list of icon URLs representing the tool
@@ -30,6 +31,7 @@ class McpTool
      */
     public function __construct(
         public ?string $name = null,
+        public ?string $title = null,
         public ?string $description = null,
         public ?ToolAnnotations $annotations = null,
         public ?array $icons = null,

src/Schema/Tool.php

@@ -33,6 +33,7 @@
  * }
  * @phpstan-type ToolData array{
  *     name: string,
+ *     title?: string,
  *     inputSchema: ToolInputSchema,
  *     description?: string|null,
  *     annotations?: ToolAnnotationsData,
@@ -47,6 +48,7 @@ class Tool implements \JsonSerializable
 {
     /**
      * @param string                $name         the name of the tool
+     * @param ?string               $title        Optional human-readable title for display in UI
      * @param ?string               $description  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.
@@ -58,6 +60,7 @@ class Tool implements \JsonSerializable
      */
     public function __construct(
         public readonly string $name,
+        public readonly ?string $title,
         public readonly array $inputSchema,
         public readonly ?string $description,
         public readonly ?ToolAnnotations $annotations,
@@ -95,19 +98,21 @@ public static function fromArray(array $data): self
         }
 
         return new self(
-            $data['name'],
-            $inputSchema,
-            isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
-            isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
-            isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
-            isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
-            $outputSchema,
+            name: $data['name'],
+            title: isset($data['title']) && \is_string($data['title']) ? $data['title'] : null,
+            inputSchema: $inputSchema,
+            description: isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
+            annotations: isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
+            icons: isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
+            meta: isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
+            outputSchema: $outputSchema,
         );
     }
 
     /**
      * @return array{
      *     name: string,
+     *     title?: string,
      *     inputSchema: ToolInputSchema,
      *     description?: string,
      *     annotations?: ToolAnnotations,
@@ -118,10 +123,11 @@ public static function fromArray(array $data): self
      */
     public function jsonSerialize(): array
     {
-        $data = [
-            'name' => $this->name,
-            'inputSchema' => $this->inputSchema,
-        ];
+        $data = ['name' => $this->name];
+        if (null !== $this->title) {
+            $data['title'] = $this->title;
+        }
+        $data['inputSchema'] = $this->inputSchema;
         if (null !== $this->description) {
             $data['description'] = $this->description;
         }

src/Schema/ToolAnnotations.php

@@ -28,7 +28,7 @@
 class ToolAnnotations implements \JsonSerializable
 {
     /**
-     * @param ?string $title           a human-readable title for the tool
+     * @param ?string $title           a human-readable title for the tool — deprecated for display in favor of `Mcp\Schema\Tool::$title` per MCP spec revision 2025-06-18; retained for backward compatibility
      * @param ?bool   $readOnlyHint    if true, the tool does not modify its environment
      * @param ?bool   $destructiveHint If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates.
      * @param ?bool   $idempotentHint  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`)