### Problem/Motivation #3583031 laid out the two readings of `access()`: "can this invocation proceed" and "may this account run this tool". !171 documents the current contract - `access()` is the invocation gate, requiring validated values before the runtime `checkAccess()`. What is missing is the other reading as first-class API: a static, values-free check that consumers can run across many tools without instantiating them. Two consumers want it today: * A tool picker (#3583020) has no values to supply and only needs "may this account run this tool". * The MCP bridge's `tools/list` advertises tools the caller cannot execute (#3618720 on mcp_server_tool_bridge) - filtering the advertised list needs a check that works from the discovered definitions alone, cheaply and cacheably. Today the only access surface is the instance-level `access()`/`checkAccess()`, so every static question pays for instantiation and input plumbing, and permission-only denials cannot be told apart from runtime ones. ### Proposed resolution 1. Add a `permissions` array to the tool definition: a `#[Tool(permissions: [...])]` attribute parameter holding a list of permission strings, exposed on `ToolDefinition`, empty by default. Derivers can set it per derivative. 2. Add `checkPermissionAccess()` to `ToolManager`. It reads the discovered definition only - no plugin instantiation - and checks the declared permissions via `AccessResult::allowedIfHasPermissions()` (conjunctive: every listed permission is required). The result carries `user.permissions` cacheability so listings can cache. When no permissions are declared it returns allowed, so existing tools are unaffected (no BC break). 3. Add a `checkPermissionAccess()` pass-through on `ToolBase` that calls the manager, for symmetry at the instance level. 4. Compose `access()`: the permission check runs first (static, cheap, short-circuits), `andIf` the existing `checkAccess()`, which becomes the runtime-focused check (entity access, state-dependent logic). The !171 docblock gets a matching touch-up in the same MR. 5. Document the override contract: a tool that overrides `access()` directly keeps its behavior; it should call the manager check (or parent) if it wants the declared permissions enforced. ### Open questions * Conjunctive is the proposed default (matches `allowedIfHasPermissions()`); if a real any-of case appears, an OR form can be added later rather than complicating the array now. * tool_belt mirrors admin UI permissions inside `checkAccess()` today. Once this lands, those pure-permission checks can migrate into declared `permissions`, leaving `checkAccess()` runtime-only - that is a belt follow-up, not this issue. ### Release note (when this lands) Tools can declare required permissions in their definition (`#[Tool(permissions: [...])]`). `ToolManager::checkPermissionAccess()` checks them statically from the definition, without instantiating the tool, so pickers and advertisement listings can filter by account. `access()` now checks declared permissions before the runtime `checkAccess()`. Tools that declare no permissions behave exactly as before. ### Remaining tasks * Attribute parameter, definition getter, discovery plumbing. * Manager check with cacheability, ToolBase pass-through, `access()` composition. * Kernel coverage: declared permissions granted and missing, empty declaration, cacheability metadata, deriver-set permissions, composition with a runtime `checkAccess()` denial. * !171 docblock touch-up. Related: #3583031 (the access() contract discussion this follows through on), #3583020 (tool picker), #3618720 on mcp_server_tool_bridge (`tools/list` filtering). ### AI usage (if applicable) * [ ] 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.