## Goal Tool stays consumer-agnostic. Give consumers (the Drush CLI, `mcp_server`, a future planner) enough introspectable metadata to understand and present a tool they did not author, before invoking it. ## Triage (2026-09-16) Rescoped against `1.0.x` at 85a73d1. Most of the original proposal has been decided elsewhere. What remains is Drush wiring. Settled since this was filed: - **Schema shape.** Tool ships a `json_schema` normalizer stack (`ContextDefinitionNormalizer`, `MapDefinitionNormalizer`) behind the `tool.definition_serializer` service. It emits `enum` from `AllowedValues` / `Choice`, map `properties`, list `items`, numeric bounds, `format`, `pattern`, and `const` (#3582972, pinned by `RicherSchemaEmissionTest`). #3583014 adds `examples`. The "Drupal-native array, no JSON Schema in Tool" argument in the original proposal is withdrawn. The open question on schema shape is closed: it is JSON Schema. - **`mcp_server_tool_bridge` already consumes it.** `McpToolConfigDeriver::buildInputSchema()` calls `ToolDefinitionSerializer::normalizeInputSchema()`. There is no consumer-side transform step to design. - **`operation` and `destructive`** are in `tool:info --format=json`. Confirmed. - **Typed outputs.** #3582942 landed. #3583015 added the `OutputDefinition` family, and the serializer has `normalizeOutputDefinitions()`. - **Requirements semantics.** #3582975 documented `checkRequirements()` as a configuration-time signal that `execute()` and `access()` never consult, and named `tool:info` / `tool:search` as the CLI consumers that should display status. Nothing in `src/Drush/` calls it yet. - **Access.** `ToolBase::access()` resolves input values before calling `checkAccess()`, so it cannot be evaluated from a definition alone, and there is no declarative permission list to surface. Dropped from this issue. A model change would be its own proposal. - **Enforced `operation` contract** and **locator input flag**: dropped. Nothing in the codebase or the queue asks for them. Reopen as separate issues if a consumer needs one. ## Remaining scope Every item lives in `src/Drush/Commands/`. `tool:info` and `tool:list` have not changed since this issue was filed except for exit codes (#3582970). ### 1. Emit the JSON Schema from `tool:info` `ToolInfoCommand::outputInfoAsJson()` flattens each input to `type`, `label`, `description`, `required`, `multiple`, `locked`. A consumer still sees `variant: string` instead of `enum: [info, success, warning]`, and `props: map` instead of its properties. Replace the hand-built `inputs` and `outputs` arrays with the serializer: ```php $tool = $this->toolManager->createInstance($tool_id, [], $invoker); $data['input_schema'] = $this->toolDefinitionSerializer->normalizeInputSchema($tool, include_locked: TRUE); $data['output_schema'] = $this->toolDefinitionSerializer->normalizeOutputDefinitions($tool); ``` The serializer takes a `ToolInterface` instance because normalization is invoker-aware (`ToolDefinitionNormalizeEvent`). `ToolInfoCommand` works from the definition today and `ToolRunCommand` passes no invoker to `createInstance()`. Introduce a Drush `Invoker` and pass it from all the `tool:*` commands. #3582977 needs the same invoker for its workflow-only filter, so land the invoker here and let #3582977 build on it. Table and markdown output: add a `Constraints` column for scalar inputs (enum values, bounds, format) and expand map properties as nested rows. ### 2. Requirement status in `tool:info`, `tool:list`, `tool:search` Call `checkRequirements()` on the instance and catch `RequirementsException`: - `tool:info`: a `Requirements:` line showing `Met` or the exception message. JSON: `"requirements": {"met": false, "message": "..."}`. - `tool:list` / `tool:search`: a `Requirements` column plus `--unmet=show|hide|only` (default `show`; per #3582975 the tool stays visible with an indicator). ### 3. `--format=json` for `tool:list` and `tool:search` Both support only `table` and `markdown`. Emit the same per-tool fields as `tool:info` minus the schemas: `id`, `label`, `description`, `operation`, `destructive`, `provider`, `requirements`. Each item can ship as its own MR. Item 1 is what #3583012 (the `use-drupal-tools` skill) waits on. ## Out of scope - `mcp_server` Resource / Resource Template surfacing. The mapping from `ToolOperation` onto MCP surfaces (`Explain` / `Read` with no inputs is a Resource, with locator inputs a Resource Template, otherwise a Tool) still holds and belongs in the `mcp_server` queue. - Runtime operand discovery (valid input values at call time). - Declarative permissions on `#[Tool]`. ## Related - #3582972 richer JSON Schema emission (landed) - #3582975 `checkRequirements()` as a configuration-time signal (closed) - #3582977 filter workflow-only tools from one-shot CLI invokers (needs the Drush invoker from item 1) - #3583012 `use-drupal-tools` agent skill (waits on item 1) - #3583014 example values in JSON Schema - #3583015 `OutputDefinition` family - #3582942 `tool:run` masked failure messages (landed) ## AI usage - [x] **AI Assisted Issue:** This issue was generated with AI assistance, but was reviewed and refined by the creator.