diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json
index 797d2807508f..ea2002a49b60 100644
--- a/packages/protocol/openapi.json
+++ b/packages/protocol/openapi.json
@@ -1075,7 +1075,8 @@
                       {
                         "type": "null"
                       }
-                    ]
+                    ],
+                    "description": "Set parentID to create a subagent session at the parent's location; set agent to choose its agent (otherwise it uses the default) and start it with session.prompt. After each completed round, the child sends a `<subagent>` report to the parent's inbox and wakes the parent unless it has a staged revert."
                   },
                   "title": {
                     "anyOf": [
diff --git a/packages/protocol/src/groups/session.ts b/packages/protocol/src/groups/session.ts
index b0f8be8dc5cb..1ac6b5bb460a 100644
--- a/packages/protocol/src/groups/session.ts
+++ b/packages/protocol/src/groups/session.ts
@@ -167,7 +167,10 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S, FormI ext
       HttpApiEndpoint.post("session.create", "/api/session", {
         payload: Schema.Struct({
           id: Session.ID.pipe(Schema.optional),
-          parentID: Session.ID.pipe(Schema.optional),
+          parentID: Session.ID.pipe(Schema.optional).annotate({
+            description:
+              "Set parentID to create a subagent session at the parent's location; set agent to choose its agent (otherwise it uses the default) and start it with session.prompt. After each completed round, the child sends a `<subagent>` report to the parent's inbox and wakes the parent unless it has a staged revert.",
+          }),
           title: Schema.String.pipe(Schema.optional),
           agent: Agent.ID.pipe(Schema.optional),
           model: Model.Ref.pipe(Schema.optional),