### Problem/Motivation Zero files in `src/` carry `@api` or `@internal` markers, and no `tool.api.php` exists. At RC1 the entire surface freezes _implicitly_ — including subsystems that were never meant as public API. Annotation is the only lever for post-1.0 refactoring freedom, and project-application reviewers expect `tool.api.php` for the alter hooks. Surface that needs an explicit decision (grown since beta2): - **Stable API**: `ToolInterface`, `ToolBase`, `#[Tool]` attribute, `ExecutableResult`, `FormattedExecutableResult`, `InputDefinitionInterface` + definition classes, `ToolOperation`, the four events in `src/Event/`, `RequirementsException`/`InputException`. - **Likely @internal**: `TypedInputsTrait`/`TypedOutputsTrait` internals, the three normalizers + `ToolDefinitionSerializer`, the TypedData adapters and their manager, `src/Form/*`, the event subscribers (`InputTypeCoercionSubscriber`, `RecursiveToolValueTransformSubscriber`). - **Needs a contract decision**: `src/Handle/` — `ToolHandleStoreInterface` is fine, but `EntityHandleTransformer` is a non-final public service with no interface; make it final, or extract an interface, or mark `@internal`. - **Document as API**: subscriber priority conventions (invoker-specific 100 \> generic coercion 50 \> recursive -100) — currently only in a docblock, but it is a real contract for third-party subscribers. ### Proposed resolution 1. Sweep `src/` and both submodules adding `@api`/`@internal` per the buckets above (adjust in review). 2. Add `tool.api.php` documenting `hook_tool_info_alter()` and the (renamed, see prefix issue) adapter alter hook, with `@code` examples. 3. Settle the `EntityHandleTransformer` contract. 4. Add a short "API stability" section to the README/ #3582955 docs pointing at the markers. ### API changes None functional; this issue _defines_ what the API is. Blocking for RC1 by definition. ### AI usage (if applicable) - [x] **AI Assisted Issue:** This issue was generated with AI assistance, but was reviewed and refined by the creator. - [x] **AI Assisted Code:** This code was mainly generated by a human, with AI autocompleting or parts AI generated, but under full human supervision. - [x] **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.