> ⚠️ **Postponed pending approval.** Part of the [Chat Fundamentals plan](https://git.drupalcode.org/project/ai/-/work_items/3586640); awaits maintainer approval ([approval issue](https://git.drupalcode.org/project/ai/-/work_items/3586639)). Targets the **1.6.x branch once it is created**. **Depends on:** nothing (wave 1 of the [meta plan](https://git.drupalcode.org/project/ai/-/work_items/3586640)). Pairs with the content-blocks child issue (03) for block shape validation and the ai_agents pre-tool confirmation child issue (08) for gating — see the meta issue's child list for links. ### Problem/Motivation Tool definitions in the ai module carry no machine-readable behavior hints. A `FunctionCall` plugin declares a name, description and properties — nothing states whether the tool is read-only, destructive, idempotent, or talks to the outside world. Without that, no consumer can implement generic safety behavior such as "ask the user before running destructive tools" (the ai_agents pre-tool confirmation child issue); every gating decision would need a hardcoded tool list. MCP already defines exactly this vocabulary: `ToolAnnotations` with `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Importantly, the spec's defaults are conservative: **when absent, `destructiveHint` and `openWorldHint` are assumed `true`** — an unannotated tool is presumed dangerous. That is the correct safe default for any gating built on top. Separately, tools have no sanctioned way to emit user-facing rich output. `ExecutableFunctionCallInterface::getReadableOutput(): string` is the only result channel, and it serves two masters: it is what the model reads *and* what (indirectly) reaches the user. A weather tool that wants to hand the frontend a structured payload for a nice card has nowhere to put it — `StructuredExecutableFunctionCallInterface::getStructuredOutput()` exists but is model-agnostic data with no user-facing semantics, and the agent loop currently discards it anyway (see the ai_agents structured-tool-output child issue). ### Proposed resolution **Tool annotations:** - Add an optional `annotations` array property to the `FunctionCall` attribute (`src/Attribute/FunctionCall.php`) accepting the MCP `ToolAnnotations` shape, so tool authors declare hints declaratively: ```php #[FunctionCall( id: 'entity_delete', ... annotations: ['destructiveHint' => TRUE, 'idempotentHint' => FALSE], )] ``` - Add `setAnnotations(array $annotations): void` / `getAnnotations(): array` to `ToolsFunctionInput` (`src/OperationType/Chat/Tools/ToolsFunctionInput.php`), and have `FunctionCallBase::normalize()` copy the attribute value onto the built `ToolsFunctionInput`. - Document the MCP absence defaults (assume destructive/open-world) in the method docblocks and in the developer docs. - Provider clients ignore annotations when building LLM API payloads — annotations are consumer-side hints, so **no provider changes are needed** and nothing new is sent to any AI vendor. **Rich tool results:** - Add `Drupal\ai\Service\FunctionCalling\ContentBlockProducerInterface` with a single method `getContentBlocks(): array`, returning MCP content-block arrays (shape defined in the content-blocks child issue). Tools that implement it can emit user-facing blocks (`annotations.audience = ["user"]`) alongside their model-facing readable output. The interface lives in ai so ai_agents and any future consumer share one contract; the ai_agents wiring is its own child issue. **Tests:** unit coverage that attribute annotations survive `normalize()` onto `ToolsFunctionInput`, and that `renderFunctionArray()` / provider payload building is unaffected. ### Backwards compatibility Additive attribute property, additive methods on `ToolsFunctionInput`, and a new optional interface. Existing tools are unaffected; unannotated tools simply fall under the spec's conservative defaults *only* where a consumer opts into annotation-driven behavior. ### AI Assistance Yes, AI was used to explore the codebase and draft this issue.