## Description The `ToolPluginInterface` contract currently allows a single tool plugin to expose multiple MCP tools through `getTools(): array` and `getRegistrations(): iterable`. In practice, this multi-tool capability is unused by every plugin that ships with the module. `EchoTool` and `ContentLookupTool` each return a single-element array; `ToolApi` is multi-instance via derivatives (one derivative per `McpToolConfig` entity), where each derivative also returns one tool. The multi-tool shape forces an awkward contract — composite `plugin_id:tool_id` MCP names, per-tool access checks, composite-ID parsing helpers — for zero observed benefit. Authors who want N tools can write N plugins (or N derivatives), which is simpler than packing them into one plugin. Drop multi-tool support entirely so the contract reads "one plugin instance = one MCP tool." Per `AGENTS.md`, the module is pre-release; no backwards-compatibility layer or migration path is required. ## Acceptance criteria - [ ] `ToolPluginInterface::getTools(): array` is removed. Tool metadata (description, inputSchema, annotations like destructive/readOnly/idempotent/openWorld) is sourced from the `#[Tool]` attribute / plugin definition, not from a `getTools()` array. - [ ] `ToolPluginInterface::getRegistrations(): iterable` collapses to a single registration per plugin instance — either renamed to `getRegistration(): ToolRegistration` or kept iterable but documented and implemented as yielding exactly one. The base class implementation in `ToolPluginBase` builds it from plugin-definition fields. - [ ] `ToolPluginInterface::checkToolAccess(string $toolId, AccountInterface $account)` is removed. `checkAccess(AccountInterface $account)` is the only access hook on a tool plugin. - [ ] `ToolPluginManager::getAllTools()`, `ToolPluginManager::getTool(string $fullToolId)`, and `ToolPluginManager::parseToolId(string $fullToolId)` are removed. Tool lookup happens by registration `mcpName` (which equals the plugin id / derivative id) — no composite-ID parsing. - [ ] The `plugin_id:tool_id` MCP name format is dropped. The MCP-visible name equals the plugin id (e.g. `echo`) or the derivative id (e.g. `tool_api:search_nodes`). `ToolPluginBase::getRegistration()` no longer concatenates `pluginId . ':' . toolId`. - [ ] `EchoTool` and `ContentLookupTool` (in `modules/mcp_server_examples/`) are updated to the new contract — schema and metadata expressed via the `#[Tool]` attribute or returned from purpose-built methods, not via `getTools()`. - [ ] `ToolApi` (in `modules/mcp_server_tool_bridge/`) is updated to the new contract. Its derivative definitions already carry `mcp_tool_name`, `tool_id`, and `description`; the simplification should remove the now-redundant `getTools()` override and the duplication between `getTools()` and `getRegistrations()`. - [ ] `McpServerFactory::registerTools()` (which iterates `$tool->getRegistrations()`) is updated for the new shape. - [ ] Documentation in `references/tools/index.md`, `references/tools/plugin-contract.md`, `references/tools/tool-registration.md`, and `references/tools/tool-api-bridge.md` is updated to describe the 1:1 contract. Any wording referring to "multi-tool plugins" is removed. - [ ] Existing tests that exercise the old contract are updated; no new "is a multi-tool plugin" test paths remain. PHPCS, PHPStan, and the full test suite (core + `mcp_server_tool_bridge` + `mcp_server_oauth`) pass. ## Additional context **Bridge architecture review:** While doing this work, also evaluate the `mcp_server_tool_bridge` architecture. With multi-tool removed, `ToolApi` becomes a deriver-driven plugin where each derivative is effectively a single-tool binding to one Tool API tool. Consider whether the deriver + plugin split is still the right shape, or whether a flatter alternative (for example, `McpToolConfig` entities directly producing registrations without going through a Tool API plugin instance) would be clearer. The decision can be deferred to a follow-up issue if it would expand scope, but the evaluation should be documented. **Affected files (non-exhaustive):** - `src/Plugin/ToolPluginInterface.php` - `src/Plugin/ToolPluginBase.php` - `src/Plugin/ToolPluginManager.php` - `src/Plugin/ToolRegistration.php` - `src/Attribute/Tool.php` (may need new fields for tool-level metadata previously in `getTools()`) - `src/McpServerFactory.php` - `modules/mcp_server_examples/src/Plugin/Tool/EchoTool.php` - `modules/mcp_server_examples/src/Plugin/Tool/ContentLookupTool.php` - `modules/mcp_server_tool_bridge/src/Plugin/Tool/ToolApi.php` - `modules/mcp_server_tool_bridge/src/Plugin/Derivative/McpToolConfigDeriver.php` - `references/tools/*.md` **Out of scope:** any backwards-compatibility shim, deprecation path, or update hook — the module is pre-release.