### Problem/Motivation [#3583078](https://git.drupalcode.org/project/tool/-/work_items/3583078) decided the runner split: `ToolRunner::run()` is the one execution sequence and `ToolInvocation` the per-call result. Phases 1 and 2 landed in [!202](https://git.drupalcode.org/project/tool/-/merge_requests/202) — the runner and invocation object, with `tool:run` and the AI connector adopting them. The stateful methods on `ToolInterface` — the per-call sequence a caller drives on the instance itself (`setInputValue()`, `validateInputs()`, `access()`, `execute()`, `getResult()`, `getFormattedResult()`, `setFailureResult()`, the output value accessors) — still exist as the pre-runner path. Two live sequences are two places the contract can drift, which is exactly what the runner exists to remove. `ToolInvocation::getTool()` is the `@internal` bridge kept only so ai_agents can reach the instance during the deprecation window. ### Proposed resolution Phase 3 of #3583078: turn `ToolBase`'s stateful invocation methods into deprecated wrappers that point at `ToolRunner::run()`, in a 1.x minor. Deprecating is not a BC break; only removing is, and that is phase 4 for the next major. rc1 freezes `ToolRunner::run()`'s signature and `ToolInvocation`'s public methods, so this lands without touching the frozen surface. * Inventory the stateful methods and mark each `@deprecated in tool:1.x.0 and is removed from tool:2.0.0. Use \Drupal\tool\Tool\ToolRunner::run() instead.`, with `@see` and a `@trigger_error(E_USER_DEPRECATED)` per core's deprecation policy. * Convert in-tree callers off the stateful path: the tests that drive `$tool->setInputValue()` / `execute()` directly. The Explorer execute form is [#3583089](https://git.drupalcode.org/project/tool/-/work_items/3583089). * Out-of-tree callers have their own adoption issues and will see the deprecation until they land: bridge [#3618734](https://git.drupalcode.org/project/mcp_server_tool_bridge/-/work_items/3618734), mcp_tools [#3613063](https://git.drupalcode.org/project/mcp_tools/-/work_items/3613063), eca_tool [#3589877](https://git.drupalcode.org/project/eca_tool/-/work_items/3589877). * Deprecate `ToolInvocation::getTool()` alongside — it leaves with the stateful path — once ai_agents no longer needs the instance. * Add a migration note to the developers docs (invoking a tool). ### Remaining tasks * [ ] Inventory the stateful `ToolInterface` methods; settle the deprecation message and version. * [ ] Deprecated wrappers with `@trigger_error`, pinned by a deprecation test. * [ ] Convert in-tree direct callers to the runner ([#3583089](https://git.drupalcode.org/project/tool/-/work_items/3583089) covers the Explorer form). * [ ] Deprecate `ToolInvocation::getTool()` when ai_agents is off it. * [ ] Docs: migration note. * [ ] File phase 4 (removal) against 2.x once this lands. ### API changes Deprecations only, no removals. The rc1-frozen surface (`ToolRunner::run()`, `ToolInvocation`'s public methods) is untouched. ### 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.