docs: explain why the mcpReq.send structural cast is needed and sound

Author: felixweinberger

packages/core/src/shared/protocol.ts

@@ -609,7 +609,10 @@ export abstract class Protocol<ContextT extends BaseContext> {
                 method: request.method,
                 _meta: request.params?._meta,
                 signal: abortController.signal,
-                // Arrow literals can't carry overload signatures; cast asserts this impl matches the overloaded property type.
+                // BaseContext.mcpReq.send is declared with two overloads (spec-method-keyed and explicit-schema). Arrow
+                // literals can't carry overload signatures, so the inferred single-signature type isn't assignable to
+                // that overloaded property type. The cast is sound: this impl dispatches both overload paths via the
+                // isStandardSchema guard, and sendRequest validates the result against the resolved schema either way.
                 send: ((r: Request, schemaOrOptions?: StandardSchemaV1 | TaskRequestOptions, maybeOptions?: TaskRequestOptions) => {
                     if (isStandardSchema(schemaOrOptions)) {
                         return sendRequest(r, schemaOrOptions, maybeOptions);