Refactor annotation handling to use ToolAnnotation class

Replaced array-based annotations with the ToolAnnotation class for improved structure and consistency. Updated ToolInterface, implementations, tests, and documentation to align with this change. This enhances clarity and sets a foundation for future extensibility of tool annotations.

Author: klapaudius

README.md

@@ -147,6 +147,8 @@ This helps you rapidly develop and debug tools by:
 - Displaying formatted results or detailed error information
 - Supporting complex input types including objects and arrays
 
+**For deep diving into tools creation please take a look at dedicated documentation [Here](https://github.com/klapaudius/symfony-mcp-server/blob/master/docs/building_tools.md)**
+
 ### Visualizing MCP Tools with Inspector
 
 You can also use the Model Context Protocol Inspector to visualize and test your MCP tools:

src/Services/ToolService/Annotation/ToolAnnotation.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace KLP\KlpMcpServer\Services\ToolService\Annotation;
+
+class ToolAnnotation
+{
+    /**
+     * @var string  A human-readable title for the tool, useful for UI display
+     */
+    private string $title;
+
+    /**
+     * @var bool If true, indicates the tool does not modify its environment
+     */
+    private bool $readOnlyHint;
+
+    /**
+     * @var bool If true, the tool may perform destructive updates (only meaningful when readOnlyHint is false)
+     */
+    private bool $destructiveHint;
+
+    /**
+     * @var bool If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when readOnlyHint is false);
+     */
+    private bool $idempotentHint;
+
+    /**
+     * @var bool If true, the tool may interact with an “open world” of external entities;
+     */
+    private bool $openWorldHint;
+
+    public function __construct(
+        ?string $title = null,
+        ?bool $readOnlyHint = null,
+        ?bool $destructiveHint = null,
+        ?bool $idempotentHint = null,
+        ?bool $openWorldHint = null
+    )
+    {
+        $this->title = $title ?? '-';
+        $this->readOnlyHint = $readOnlyHint ?? false;
+        $this->destructiveHint = $destructiveHint ?? true;
+        $this->idempotentHint = $idempotentHint ?? false;
+        $this->openWorldHint = $openWorldHint ?? true;
+    }
+
+    public function getTitle(): string
+    {
+        return $this->title;
+    }
+
+    public function isReadOnlyHint(): bool
+    {
+        return $this->readOnlyHint;
+    }
+
+    public function setReadOnlyHint(bool $readOnlyHint): void
+    {
+        $this->readOnlyHint = $readOnlyHint;
+    }
+
+    public function isDestructiveHint(): bool
+    {
+        return $this->destructiveHint;
+    }
+
+    public function isIdempotentHint(): bool
+    {
+        return $this->idempotentHint;
+    }
+
+    public function isOpenWorldHint(): bool
+    {
+        return $this->openWorldHint;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'title' => $this->title,
+            'readOnlyHint' => $this->isReadOnlyHint(),
+            'destructiveHint' => $this->isDestructiveHint(),
+            'idempotentHint' => $this->isIdempotentHint(),
+            'openWorldHint' => $this->isOpenWorldHint(),
+        ];
+    }
+}

src/Services/ToolService/Examples/HelloWorldTool.php

@@ -2,6 +2,7 @@
 
 namespace KLP\KlpMcpServer\Services\ToolService\Examples;
 
+use KLP\KlpMcpServer\Services\ToolService\Annotation\ToolAnnotation;
 use KLP\KlpMcpServer\Services\ToolService\ToolInterface;
 
 class HelloWorldTool implements ToolInterface
@@ -30,9 +31,9 @@ public function getInputSchema(): array
         ];
     }
 
-    public function getAnnotations(): array
+    public function getAnnotations(): ToolAnnotation
     {
-        return [];
+        return new ToolAnnotation;
     }
 
     public function execute(array $arguments): string

src/Services/ToolService/Examples/VersionCheckTool.php

@@ -2,6 +2,7 @@
 
 namespace KLP\KlpMcpServer\Services\ToolService\Examples;
 
+use KLP\KlpMcpServer\Services\ToolService\Annotation\ToolAnnotation;
 use KLP\KlpMcpServer\Services\ToolService\ToolInterface;
 use stdClass;
 use Symfony\Component\HttpKernel\Kernel;
@@ -27,9 +28,9 @@ public function getInputSchema(): array
         ];
     }
 
-    public function getAnnotations(): array
+    public function getAnnotations(): ToolAnnotation
     {
-        return [];
+        return new ToolAnnotation;
     }
 
     public function execute(array $arguments): string

src/Services/ToolService/ToolInterface.php

@@ -2,6 +2,8 @@
 
 namespace KLP\KlpMcpServer\Services\ToolService;
 
+use KLP\KlpMcpServer\Services\ToolService\Annotation\ToolAnnotation;
+
 interface ToolInterface
 {
     /**
@@ -15,7 +17,7 @@ public function getDescription(): string;
 
     public function getInputSchema(): array;
 
-    public function getAnnotations(): array;
+    public function getAnnotations(): ToolAnnotation;
 
     public function execute(array $arguments): mixed;
 }

src/Services/ToolService/ToolRepository.php

@@ -124,14 +124,12 @@ public function getToolSchemas(): array
                     'required' => [],
                 ];
             }
-            if (! empty($tool->getAnnotations())) {
-                $injectArray['annotations'] = $tool->getAnnotations();
-            }
 
             $schemas[] = [
                 'name' => $tool->getName(),
                 'description' => $tool->getDescription(),
                 'inputSchema' => $tool->getInputSchema(),
+                'annotations' => $tool->getAnnotations()->toArray(),
                 ...$injectArray,
             ];
         }

src/stubs/tool.stub

@@ -2,6 +2,7 @@
 
 namespace {{ namespace }};
 
+use KLP\KlpMcpServer\Services\ToolService\Annotation\ToolAnnotation;
 use KLP\KlpMcpServer\Services\ToolService\ToolInterface;
 
 class {{ className }} implements ToolInterface
@@ -49,11 +50,11 @@ class {{ className }} implements ToolInterface
     /**
      * Get the tool annotations.
      *
-     * @return array
+     * @return ToolAnnotation
      */
-    public function getAnnotations(): array
+    public function getAnnotations(): ToolAnnotation
     {
-        return [];
+        return new ToolAnnotation;
     }
 
     /**

tests/Services/ToolService/ToolRepositoryTest.php

@@ -3,6 +3,7 @@
 namespace KLP\KlpMcpServer\Tests\Services\ToolService;
 
 use InvalidArgumentException;
+use KLP\KlpMcpServer\Services\ToolService\Annotation\ToolAnnotation;
 use KLP\KlpMcpServer\Services\ToolService\ToolInterface;
 use KLP\KlpMcpServer\Services\ToolService\ToolRepository;
 use PHPUnit\Framework\Attributes\Small;
@@ -235,7 +236,7 @@ public function test_get_tool_schemas_includes_annotations_if_present(): void
         $tool->method('getName')->willReturn('toolWithAnnotations');
         $tool->method('getDescription')->willReturn('Tool with annotations');
         $tool->method('getInputSchema')->willReturn(['type' => 'object']);
-        $tool->method('getAnnotations')->willReturn(['tag' => 'example', 'version' => '1.0']);
+        $tool->method('getAnnotations')->willReturn(new ToolAnnotation);
 
         $this->toolRepository->register($tool);
 
@@ -245,6 +246,12 @@ public function test_get_tool_schemas_includes_annotations_if_present(): void
         $this->assertSame('toolWithAnnotations', $schemas[0]['name']);
         $this->assertSame('Tool with annotations', $schemas[0]['description']);
         $this->assertSame(['type' => 'object'], $schemas[0]['inputSchema']);
-        $this->assertSame(['tag' => 'example', 'version' => '1.0'], $schemas[0]['annotations']);
+        $this->assertSame([
+            'title' => '-',
+            'readOnlyHint' => false,
+            'destructiveHint' => true,
+            'idempotentHint' => false,
+            'openWorldHint' => true
+        ], $schemas[0]['annotations']);
     }
 }