diff --git a/.secrets.baseline b/.secrets.baseline
index 7bf71107..3425b4c2 100644
--- a/.secrets.baseline
+++ b/.secrets.baseline
@@ -324,7 +324,7 @@
         "filename": "openapi/control/control.openapi.yaml",
         "hashed_secret": "2c4ea53d93a5d7661383e1c667d72270f9bf2fb6",
         "is_verified": false,
-        "line_number": 15827
+        "line_number": 15829
       }
     ],
     "src/jentic_one/auth/services/crypto.py": [
@@ -1544,5 +1544,5 @@
       }
     ]
   },
-  "generated_at": "2026-07-01T16:24:17Z"
+  "generated_at": "2026-07-10T14:14:28Z"
 }
diff --git a/openapi/control/control.openapi.yaml b/openapi/control/control.openapi.yaml
index 6981893b..ecc0cffc 100644
--- a/openapi/control/control.openapi.yaml
+++ b/openapi/control/control.openapi.yaml
@@ -70,12 +70,14 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.
           title: Resource Id
         resource_reference:
           anyOf:
           - additionalProperties: true
             type: object
           - type: 'null'
+          description: Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.
           title: Resource Reference
         resource_type:
           enum:
diff --git a/src/jentic_one/control/web/schemas/access_requests.py b/src/jentic_one/control/web/schemas/access_requests.py
index e233b5e7..916c4412 100644
--- a/src/jentic_one/control/web/schemas/access_requests.py
+++ b/src/jentic_one/control/web/schemas/access_requests.py
@@ -45,8 +45,17 @@ class AccessRequestItemRequest(BaseModel):
 
     resource_type: Literal["credential", "toolkit", "scope"]
     action: Literal["bind", "grant"]
-    resource_id: str | None = None
-    resource_reference: dict[str, Any] | None = None
+    resource_id: str | None = Field(
+        default=None,
+        description="Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID)."
+        " For toolkit:bind, you can omit this and use resource_reference instead.",
+    )
+    resource_reference: dict[str, Any] | None = Field(
+        default=None,
+        description="Look up the resource by API identity instead of by ID."
+        " For toolkit:bind, provide {vendor, name, version} to resolve the toolkit"
+        " that serves the given API. Use this when you don't know the toolkit ID.",
+    )
     to_type: str | None = None
     to_id: str | None = None
     rules: list[PermissionRuleSchema] | None = None
diff --git a/ui/openapi.json b/ui/openapi.json
index c0087f74..3e06b485 100644
--- a/ui/openapi.json
+++ b/ui/openapi.json
@@ -98,6 +98,7 @@
                 "type": "null"
               }
             ],
+            "description": "Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.",
             "title": "Resource Id"
           },
           "resource_reference": {
@@ -110,6 +111,7 @@
                 "type": "null"
               }
             ],
+            "description": "Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.",
             "title": "Resource Reference"
           },
           "resource_type": {
diff --git a/ui/src/shared/api/generated/models/AccessRequestItemRequest.ts b/ui/src/shared/api/generated/models/AccessRequestItemRequest.ts
index e6232c04..369a9d9e 100644
--- a/ui/src/shared/api/generated/models/AccessRequestItemRequest.ts
+++ b/ui/src/shared/api/generated/models/AccessRequestItemRequest.ts
@@ -8,7 +8,13 @@ import type { jentic_one__control__web__schemas__access_requests__PermissionRule
  */
 export type AccessRequestItemRequest = {
     action: AccessRequestItemRequest.action;
+    /**
+     * Explicit ID of the resource (e.g. a toolkit tk_… or credential cred_… ID). For toolkit:bind, you can omit this and use resource_reference instead.
+     */
     resource_id?: (string | null);
+    /**
+     * Look up the resource by API identity instead of by ID. For toolkit:bind, provide {vendor, name, version} to resolve the toolkit that serves the given API. Use this when you don't know the toolkit ID.
+     */
     resource_reference?: (Record<string, any> | null);
     resource_type: AccessRequestItemRequest.resource_type;
     rules?: (Array<jentic_one__control__web__schemas__access_requests__PermissionRuleSchema> | null);