[McpSdk] Improve the relation between Tool Metadata and Tool Executor

[Kocal]

Hey!

I quickly read the MCP SDK Capabilities documentation, and some code examples seem confusing to me.

I feel like there is no real link between a tool metadata and its executor. IINW, both are resolved/linked on-the-fly thanks to getName() or name comparaison from https://github.com/symfony/ai/blob/main/src/mcp-sdk/src/Capability/ToolChain.php#L37-L74

I feel like we can get some inspiration from the Symfony Messenger/Console components or other existing MCP-SDK, by using a PHP Attribute AsTool for describing the Tool's metadata, on an invokable class?

<?php
#[AsTool(
    name: 'Current time',
    description: 'Returns the current time in UTC',
    // or through a static method
    inputSchema: [
        'type' => 'object',
        'properties' => [
            'format' => [
                'type' => 'string',
                'description' => 'The format of the time to return, e.g. "Y-m-d H:i:s"',
            ],
        ],
    ]
)]
class CurrentTimeTool implements ToolExecutorInterface
{
    // or through the attribute `AsTool`
    public static function getInputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'format' => [
                    'type' => 'string',
                    'description' => 'The format of the time to return, e.g. "Y-m-d H:i:s"',
                ],
            ],
            'required' => ['format'],
        ];
    }

    public function __invoke(ToolCall $input): ToolCallResult
    {
        // ...
    }
}

[Kocal]

A colleague showed me https://github.com/symfony/ai/blob/main/src/agent/doc/index.rst#tools, and this is exactly what I describe above.

Any reasons for not doing that for MCP SDK?

[Kocal]

I've just seen the ExampleTool from examples/:

class ExampleTool implements MetadataInterface, ToolExecutorInterface
{
    public function call(ToolCall $input): ToolCallResult
    {
        $format = $input->arguments['format'] ?? 'Y-m-d H:i:s';

        return new ToolCallResult(
            (new \DateTime('now', new \DateTimeZone('UTC')))->format($format)
        );
    }

    public function getName(): string
    {
        return 'Current time';
    }

    public function getDescription(): string
    {
        return 'Returns the current time in UTC';
    }

    public function getInputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'format' => [
                    'type' => 'string',
                    'description' => 'The format of the time, e.g. "Y-m-d H:i:s"',
                    'default' => 'Y-m-d H:i:s',
                ],
            ],
            'required' => [],
        ];
    }
}

It looks much better, but I really think getName(), getDescription() and getInputSchema() could be changed for an attribute AsTool, or at least static methods.

Same suggestion for Prompt and Resource.

[Kocal]

Or, maybe we can remove MetadataInterface and ToolExecutorInterface in favor of ToolInterface:

interface ToolInterface {
    public static function getMetadata();

    public function __invoke(ToolCall $input): ToolCallResult;
}

Same suggestion for Prompt and Resource.

WDYT?