## Summary `place_components` (https://git.drupalcode.org/project/canvas/-/work_items/3591811) is merged, but its schema is as basic as it gets: one string argument, `component_structure_yaml`, holding an entire YAML document. Every part of the placement envelope — the `operations` root, the `target`, the `placement` enum, the `reference_uuid` — is taught to the model in prose and only discovered to be wrong after the call arrives. Replace it with the shape the sibling `edit_components` tool (https://git.drupalcode.org/project/canvas/-/work_items/3591812) already ships: an `operations` list of typed records, constrained with `ComplexToolItems`, with only the recursive component tree left as YAML. ## Why now The tool is still **inert** — no agent lists it — so its input shape can change without touching a prompt or breaking a released contract. That stops being true the moment the dev page-builder agent wires it up (roadmap: https://git.drupalcode.org/project/canvas/-/work_items/3591777). This is the cheapest moment to fix it. Three concrete gains: - The `operations` root stops being something the model can omit — it becomes the parameter name, so the "operations key is missing" failure disappears entirely. - `placement` becomes a provider-enforced enum via a `Choice` constraint, so an invalid placement cannot be emitted at all rather than costing a round trip. Precedent: `ai_agents`' `CreateContentType.php:58`. - The tool description stops being a format tutorial. The current ~350-character description teaches YAML grammar in prose, which is exactly the kind of thing models get wrong. `edit_components` is already built this way — a `ComplexToolItems` list of typed records with one free-form YAML field per record. Retrofitting `place_components` makes the two consistent, which matters because an agent will call them in the same turn. ## Current schema ```php context_definitions: [ 'component_structure_yaml' => new ContextDefinition( data_type: 'string', label: new TranslatableMarkup("Component structure in yml format"), description: new TranslatableMarkup("The components to place, as a YAML string containing an 'operations' list."), required: TRUE, ), ], ``` One string. The model has to produce this from the description alone: ```yaml operations: - target: content placement: below reference_uuid: abc-123 components: - sdc.my_hero: props: title: Welcome ``` ## Proposed schema Mirror `edit_components`: a schema-only item plugin describing one placement record, referenced from a `list` context definition via the `ComplexToolItems` constraint. **1. The item plugin** — schema-only, never executed. Same folder and same shape as `edit_components`' `ComponentEdit`, alongside the tools in `Plugin/AiFunctionCall/`. ```php #[FunctionCall( id: 'canvas_ai:placement_operation', function_name: 'canvas_ai_placement_operation', name: 'Placement Operation', description: 'A single placement: where to place components, plus the components to place there.', group: 'modification_tools', context_definitions: [ 'target' => new ContextDefinition( data_type: 'string', label: new TranslatableMarkup("Target"), description: new TranslatableMarkup("The region name, such as 'content', or 'parent-uuid/slot_name' to place inside a component's slot."), required: TRUE, ), 'placement' => new ContextDefinition( data_type: 'string', label: new TranslatableMarkup("Placement"), description: new TranslatableMarkup("Whether to place the components 'inside' a target that has no children yet, or 'above'/'below' the component named by reference_uuid."), required: TRUE, constraints: [ 'Choice' => ['above', 'below', 'inside'], ], ), 'reference_uuid' => new ContextDefinition( data_type: 'string', label: new TranslatableMarkup("Reference UUID"), description: new TranslatableMarkup("The UUID of the component to place above or below. Required for 'above' and 'below'; omit it for 'inside'."), required: FALSE, ), 'components' => new ContextDefinition( data_type: 'string', label: new TranslatableMarkup("Components"), description: new TranslatableMarkup("The components to place, as a YAML list starting at the top level. Each entry is a single-key map of the component ID to its 'props' and, when the component has slots, its 'slots'."), required: TRUE, ), ], )] final class PlacementOperation extends FunctionCallBase { } ``` **2. The tool argument** — `component_structure_yaml` is replaced by `operations`: ```php 'operations' => new ContextDefinition( data_type: 'list', label: new TranslatableMarkup("Placement operations"), description: new TranslatableMarkup("The placements to apply, one entry per target position."), required: TRUE, constraints: [ 'ComplexToolItems' => PlacementOperation::class, ], ), ``` The `list` branch of `ContextDefinitionNormalizer` supplies `minItems: 1`; the `ComplexToolItems` branch overwrites `items` with the child object. The rendered schema is therefore an array of objects with a minimum length, each object carrying the four properties above with `placement` as an enum. **3. `execute()`** reassembles the canonical structure — read `operations`, parse each record's `components` block, hand the result to the placement helper. That makes `CanvasAiPageBuilderHelper::generateComponentPlacementData()` and its private `computePlacement()` take an array instead of a YAML string; keep `customYamlToArrayMapper(string)` parsing its own YAML before delegating, so the live `set_component_structure` path stays byte-identical. **4. Keep the existing runtime validation.** The schema is advertised to the model, not enforced server-side, so the placement and component checks in `execute()` stay as they are. **Multiplicity is unchanged.** N placements remain one tool call with N operation records. The list moved from YAML into the schema; it did not become N calls. `components` stays a YAML string because a component tree is recursive and keyed by dynamic component IDs, neither of which a tool schema can express. ## Tests `PlaceComponentsTest` already covers the placement and component-validation paths; adapt it rather than adding a parallel test. - Fixtures become the shape the model actually sends: `operations` arrays whose `components` are YAML strings, not one YAML document per case. - Add a case asserting the rendered schema (`normalize()->renderFunctionArray()`) exposes `operations` as an array with `minItems`, the four item properties, the `placement` enum, and the item-level required list — this is the contract the change exists to create. - Add cases for an empty `operations` list and for a `components` block that is not a YAML list. - Confirm the live tool is untouched: `SetAIGeneratedComponentStructureTest` must pass unchanged. ## Explicitly out of scope - Wiring `place_components` to any agent — it stays inert until the dev page-builder agent lands. - Typing the component tree, or any change to how props and slots are expressed. - Any change to the live `set_component_structure` tool or its agents. _Issue generated with AI assistance._