### Problem/Motivation Inputs have their own definition family. Outputs do not. `Tool` attribute: ```php /** * @param \Drupal\tool\TypedData\InputDefinitionInterface[] $input_definitions * @param \Drupal\Core\Plugin\Context\ContextDefinitionInterface[] $output_definitions */ ``` `InputDefinitionInterface` extends core's `ContextDefinitionInterface` and has four concrete classes (`InputDefinition`, `EntityInputDefinition`, `ListInputDefinition`, `MapInputDefinition`). Their constructors require `$label` and `$description`, and they carry input-only state (`$locked`). Every public input API is typed against `InputDefinitionInterface`. The output side is typed against the core interface everywhere: - `TypedOutputsDefinitionInterface::addOutputDefinition(string $name, ContextDefinitionInterface $definition)` - `TypedOutputsDefinitionInterface::getOutputDefinition(): ContextDefinitionInterface` - `TypedOutputsInterface::getOutputDefinition(): ContextDefinitionInterface` - `ToolOutputDefinitionNormalizeEvent::$definition` - `ToolOutputTransformEvent::$definition` This is release blocking for three reasons. **1. Narrowing the parameter type after 1.0.0 is a BC break.** PHP parameter types are contravariant. Once `addOutputDefinition()` ships accepting `ContextDefinitionInterface`, we can never require `OutputDefinitionInterface` in 1.x. Return types can narrow later; parameters cannot. Every output-only feature we add after 1.0.0 (example values, sensitivity flags, formatting hints) has to be bolted on with `instanceof` checks against a core class we do not own, or wait for 2.0.0. `#3583014` already runs into this: it adds `examples` to `InputDefinition` and has no home for the output equivalent. **2. Descriptions are optional on outputs and nobody writes them.** Core `ContextDefinition::__construct()` puts `$description` in fifth position with a NULL default. Tool authors omit it. Every tool in `ai_automators` declares outputs like this: ```php 'id' => new ContextDefinition(data_type: 'string', label: new TranslatableMarkup('Automator ID'), required: FALSE), ``` The LLM-facing output schema then has no descriptions. `InputDefinition` solved this for inputs by making `$description` a required constructor argument. **3. We already special-case output classes we do not control.** `TypedOutputsTrait::validateOutputs()` does `instanceof MapContextDefinition || instanceof ListContextDefinition` to work around a core prototype cache bug. `EntityHandleTransformSubscriber` swaps entity output definitions for string definitions by class. `InputDefinition` objects also pass type checks as outputs, dragging `isLocked()` into a place it has no meaning. Current declarations across contrib (`grep "output_definitions: \["`): | Class | Count | | --- | --- | | `ContextDefinition` | 13 | | `EntityContextDefinition` | 4 | | `MapContextDefinition` | 2 | | `ListContextDefinition` | 1 | Declaring modules: `ai_automators` (6 tools), `mcp_server_tool_bridge` test module (3), `tool_test` (11), plus the Drush generator template `src/Drush/Generators/tool.twig` and `docs/developers/input-output-definitions.md`. ### Proposed resolution Mirror the input family one-for-one, minus `$locked`. ```php namespace Drupal\tool\TypedData; interface OutputDefinitionInterface extends ContextDefinitionInterface {} class OutputDefinition extends ContextDefinition implements OutputDefinitionInterface { public function __construct($data_type, string|TranslatableMarkup $label, string|TranslatableMarkup $description, $required = TRUE, $multiple = FALSE, $default_value = NULL, ?array $constraints = []) { parent::__construct($data_type, $label, $required, $multiple, $description, $default_value, $constraints); } public static function create($data_type = 'any') { /* same shape as InputDefinition::create(), see #3582962 */ } } class EntityOutputDefinition extends EntityContextDefinition implements OutputDefinitionInterface {} class ListOutputDefinition extends ListContextDefinition implements OutputDefinitionInterface {} class MapOutputDefinition extends MapContextDefinition implements OutputDefinitionInterface {} ``` The interface stays empty. Its job is to own the type boundary so output-only metadata lands later as a non-breaking addition. Do not add methods speculatively. Retype the public API: - `TypedOutputsDefinitionInterface::addOutputDefinition(string $name, OutputDefinitionInterface $definition): static` - `TypedOutputsDefinitionInterface::getOutputDefinition(string $name): OutputDefinitionInterface` - `TypedOutputsDefinitionInterface::getOutputDefinitions(): OutputDefinitionInterface[]` - `TypedOutputsInterface::getOutputDefinition()` / `getOutputDefinitions()` likewise - `ToolOutputDefinitionNormalizeEvent` and `ToolOutputTransformEvent` constructor and getter - `Tool` attribute `@param` docblock for `$output_definitions` No transition shim. Tool is in beta and beta carries no BC guarantee, regardless of where consuming projects are in their own release cycles. `ToolDefinition::__construct()` rejects anything in `output_definitions` that is not an `OutputDefinitionInterface`. Convert `tool_test`, the `mcp_server_tool_bridge` test module, `tool.twig`, and the docs in this issue. Open a follow-up in `ai` for the six `ai_automators` tools and land it alongside this one. Once `OutputDefinitionInterface` exists, replace the `instanceof MapContextDefinition || ListContextDefinition` check in `validateOutputs()` with the `*OutputDefinition` classes. That is the only behavior change inside `TypedOutputsTrait`. ### API changes - New: `OutputDefinitionInterface`, `OutputDefinition`, `EntityOutputDefinition`, `ListOutputDefinition`, `MapOutputDefinition` in `Drupal\tool\TypedData`. - Changed: output definition parameters and return types on `TypedOutputsDefinitionInterface`, `TypedOutputsInterface`, `ToolOutputDefinitionNormalizeEvent`, `ToolOutputTransformEvent` move from `ContextDefinitionInterface` to `OutputDefinitionInterface`. - Removed: passing a bare `ContextDefinitionInterface` in `output_definitions`. Beta, so no deprecation path and no `class_alias`. Nothing outside `tool` type-hints these interfaces (verified by code search). The only affected declarations are the 20 listed above. ### Related - #3582978 META lists "Add OutputDefinition?" with no work item. This is that work item. - #3582962 covers the `InputDefinition::create()` override this mirrors. - #3583014 adds `examples` to inputs and needs the output counterpart to have somewhere to live. - #3582976 keeps the typed-outputs metadata model stable through RC1. This issue has to land before that freeze. - #3582974 kernel coverage for the definition pipeline should include the new classes. ### AI usage (if applicable) - [x] **AI Assisted Issue:** This issue was generated with AI assistance, but was reviewed and refined by the creator. - [ ] **AI Assisted Code** - [ ] **AI Generated Code** - [ ] **Vibe Coded**