### Problem/Motivation In `ToolPluginBase::execute()`, the broad `catch (\Exception $e)` catches everything from `InvalidHandleException` (correctable input problem) to infrastructure failures (not correctable). Regardless of the failure category, `getStructuredOutput()` always includes `input_schema` when `$this->errorMessage` is set: ```php if ($this->errorMessage !== NULL) { return [ 'success' => FALSE, 'message' => $this->errorMessage, 'outputs' => [], 'input_schema' => $this->getInputSchema(), // always included ]; } ``` The access-denied path also falls into this — it sets `$this->errorMessage` and gets `input_schema` too. This means: - A handle typo → LLM sees input_schema → helpful, it can self-correct - A downstream service timeout → LLM sees input_schema → misleading, implies it should change inputs when nothing about its inputs was wrong - Access denied → LLM sees input_schema → also misleading, since access is not an input problem Including the schema on every failure dilutes the "your inputs were wrong" signal. The LLM may waste retries changing arguments when the real problem is transient infrastructure, a permissions issue, or something entirely unrelated to its argument values. ### Proposed resolution Rather than a flag property, assemble the full error output shape in `execute()` and store it directly as `$this->structuredOutputOverride`. This eliminates the `$errorMessage` property for error cases entirely — `getStructuredOutput()` doesn't need to know why it failed, it just returns the override: ```php // Input-phase errors (correctable): include input_schema. // Catch these before the access check so the LLM gets violation detail // rather than a generic "access denied" for invalid inputs. foreach (array_keys($this->getPluginInstance()->getInputDefinitions()) as $name) { if (array_key_exists($name, $this->values)) { $this->getPluginInstance()->setInputValue($name, $this->unescapePropertyKeys($this->values[$name])); $this->setContext($name, $this->getPluginInstance()->getInput($name)); } } $violations = $this->getPluginInstance()->validateInputs(); if ($violations->count() > 0) { // Input error — include schema so the LLM can self-correct. // Note: by this point setInputValue() has already fired the input // transform events that trigger definition refiners, so the schema // returned by getInputSchema() reflects any refined constraints (e.g. // bundle choices narrowed by entity_type). This is intentional: the // LLM sees the tightest applicable schema, not the base schema. $this->structuredOutputOverride = [ 'success' => FALSE, 'message' => 'Tool input validation failed: ' . $violations, 'outputs' => [], 'input_schema' => $this->getInputSchema(), ]; $this->getPluginInstance()->setFailureResult(new TranslatableMarkup('@m', ['@m' => (string) $violations])); return; } $access = $this->getPluginInstance()->access(NULL, TRUE); if (!$access->isAllowed()) { // Access denial is not an input problem — omit schema. $reason = $access instanceof AccessResultReasonInterface ? $access->getReason() : NULL; $message = $reason ? 'Tool plugin access denied: ' . $reason : 'Tool plugin access denied.'; $this->structuredOutputOverride = [ 'success' => FALSE, 'message' => $message, 'outputs' => [], ]; $this->getPluginInstance()->setFailureResult(new TranslatableMarkup('@m', ['@m' => $message])); return; } try { $this->getPluginInstance()->execute(); $this->getPluginInstance()->getFormattedResult(); } catch (\Exception $e) { // Runtime failure — not correctable by changing inputs, omit schema. $this->structuredOutputOverride = [ 'success' => FALSE, 'message' => 'Tool execution failed: ' . $e->getMessage(), 'outputs' => [], ]; $this->getPluginInstance()->setFailureResult(new TranslatableMarkup('@m', ['@m' => 'Tool execution failed: ' . $e->getMessage()])); } ``` `getStructuredOutput()` then just returns the override when set, or computes from the tool result — no special error-message branch needed. This gives the LLM a clear signal: "input_schema present" = "change your arguments and retry", "no input_schema" = "something else went wrong, retrying with different args won't help." ### Note on definition refiners and input_schema Input definition refiners fire during `setInputValue()` — so by the time `validateInputs()` runs, definitions have already been tightened based on whatever inputs the LLM provided (e.g., `entity_type = 'node'` narrows `bundle` to only the node bundles). When `input_schema` is included after a refinement-triggered violation, it reflects the _refined_ definitions — which is strictly more useful than the base schema, since it shows the LLM exactly which values are now valid given what it already provided. No special handling is needed for refinement failures: if dependency inputs have violations, the refiner is skipped and the original definition is restored, so the LLM still sees a correctable input error. ### 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:** This code was mainly generated by a human, with AI autocompleting or parts AI generated, but under full human supervision. - [ ] **AI Generated Code:** This code was mainly generated by an AI with human guidance, and reviewed, tested, and refined by a human. - [ ] **Vibe Coded:** This code was generated by an AI and has only been functionally tested.