effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/unstable/ai/McpSchema.d.ts

@@ -1,4 +1,32 @@
 /**
+ * The `McpSchema` module defines Effect Schema and RPC models for the Model
+ * Context Protocol (MCP). It provides the shared protocol vocabulary used by
+ * MCP clients and servers, including JSON-RPC request identifiers, metadata,
+ * capabilities, errors, resources, prompts, tools, logging, sampling,
+ * completions, roots, and elicitation.
+ *
+ * **Common tasks**
+ *
+ * - Describe MCP payloads with schemas such as {@link Resource}, {@link Tool},
+ *   {@link Prompt}, and {@link ContentBlock}
+ * - Build typed protocol handlers with request RPCs such as {@link Initialize},
+ *   {@link ListResources}, {@link ReadResource}, {@link ListTools}, and
+ *   {@link CallTool}
+ * - Work with protocol notifications such as
+ *   {@link ProgressNotification}, {@link ResourceUpdatedNotification}, and
+ *   {@link LoggingMessageNotification}
+ * - Use {@link ClientRpcs} and server RPC groups to derive encoded request,
+ *   notification, success, and failure message types
+ *
+ * **Gotchas**
+ *
+ * - MCP distinguishes absent fields from present fields whose value is
+ *   `undefined`; use {@link optional} and {@link optionalWithDefault} for
+ *   protocol fields so encoding omits undefined values consistently.
+ * - Capability objects are extensible. Known fields are modeled here, but
+ *   `experimental` and `extensions` allow implementations to advertise
+ *   additional protocol features.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts";
@@ -12,23 +40,39 @@ import type { RpcClientError } from "../rpc/RpcClientError.ts";
 import * as RpcGroup from "../rpc/RpcGroup.ts";
 import * as RpcMiddleware from "../rpc/RpcMiddleware.ts";
 /**
+ * Schema type returned by `optionalWithDefault`.
+ *
+ * It represents an optional struct field that supplies a default value when the
+ * field is absent during decoding or construction.
+ *
  * @since 4.0.0
  */
 export interface optionalWithDefault<S extends Schema.Top & Schema.WithoutConstructorDefault> extends Schema.withConstructorDefault<Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>> {
 }
 /**
+ * Marks a struct field as optional and supplies `defaultValue` when the field
+ * is absent.
+ *
+ * The default is used during decoding and as the constructor default for the
+ * schema field.
+ *
  * @since 4.0.0
  */
 export declare const optionalWithDefault: <S extends Schema.Top & Schema.WithoutConstructorDefault>(schema: S, defaultValue: () => Schema.optionalKey<S>["Type"]) => optionalWithDefault<S>;
 /**
+ * Creates an optional MCP struct-field schema from a required schema.
+ *
+ * The field may be absent, and explicit `undefined` values are omitted when
+ * encoding.
+ *
  * @since 4.0.0
  */
 export declare const optional: <S extends Schema.Top>(schema: S) => Schema.decodeTo<Schema.optional<S>, Schema.optionalKey<S>>;
 /**
  * A uniquely identifying ID for a request in JSON-RPC.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare const RequestId: Schema.Union<[
     typeof Schema.String,
@@ -37,16 +81,16 @@ export declare const RequestId: Schema.Union<[
 /**
  * A uniquely identifying ID for a request in JSON-RPC.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export type RequestId = typeof RequestId.Type;
 /**
  * A progress token, used to associate progress notifications with the original
  * request.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare const ProgressToken: Schema.Union<[
     typeof Schema.String,
@@ -56,8 +100,8 @@ export declare const ProgressToken: Schema.Union<[
  * A progress token, used to associate progress notifications with the original
  * request.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export type ProgressToken = typeof ProgressToken.Type;
 declare const RequestMeta_base: Schema.Opaque<RequestMeta, Schema.Struct<{
@@ -102,8 +146,13 @@ declare const RequestMeta_base: Schema.Opaque<RequestMeta, Schema.Struct<{
     }>>, never, never>;
 }>, keyof Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema for optional MCP request metadata.
+ *
+ * Request metadata may include a progress token that asks the receiver to send
+ * out-of-band progress notifications for the request.
+ *
  * @category common
+ * @since 4.0.0
  */
 export declare class RequestMeta extends RequestMeta_base {
 }
@@ -121,8 +170,13 @@ declare const ResultMeta_base: Schema.Opaque<ResultMeta, Schema.Struct<{
     readonly _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, keyof Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema for optional MCP result metadata.
+ *
+ * The `_meta` field is reserved for protocol, extension, or implementation
+ * metadata attached to a result.
+ *
  * @category common
+ * @since 4.0.0
  */
 export declare class ResultMeta extends ResultMeta_base {
 }
@@ -140,21 +194,30 @@ declare const NotificationMeta_base: Schema.Opaque<NotificationMeta, Schema.Stru
     readonly _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, keyof Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema for optional MCP notification metadata.
+ *
+ * The `_meta` field is reserved for protocol, extension, or implementation
+ * metadata attached to a notification.
+ *
  * @category common
+ * @since 4.0.0
  */
 export declare class NotificationMeta extends NotificationMeta_base {
 }
 /**
  * An opaque token used to represent a cursor for pagination.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare const Cursor: typeof Schema.String;
 /**
- * @since 4.0.0
+ * Type represented by the MCP cursor schema.
+ *
+ * A cursor is an opaque string token used to continue paginated requests.
+ *
  * @category common
+ * @since 4.0.0
  */
 export type Cursor = typeof Cursor.Type;
 declare const PaginatedRequestMeta_base: Schema.Opaque<PaginatedRequestMeta, Schema.Struct<{
@@ -209,8 +272,13 @@ declare const PaginatedRequestMeta_base: Schema.Opaque<PaginatedRequestMeta, Sch
     }>>, never, never>;
 }>, keyof Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema for MCP request metadata used by paginated requests.
+ *
+ * It includes the base request metadata fields plus an optional cursor
+ * indicating where the server should continue listing results.
+ *
  * @category common
+ * @since 4.0.0
  */
 export declare class PaginatedRequestMeta extends PaginatedRequestMeta_base {
 }
@@ -238,20 +306,29 @@ declare const PaginatedResultMeta_base: Schema.Opaque<PaginatedResultMeta, Schem
     readonly _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, keyof Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema for MCP result metadata returned by paginated operations.
+ *
+ * It includes the base result metadata fields plus an optional `nextCursor`,
+ * which indicates that more results may be available.
+ *
  * @category common
+ * @since 4.0.0
  */
 export declare class PaginatedResultMeta extends PaginatedResultMeta_base {
 }
 /**
  * The sender or recipient of messages and data in a conversation.
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare const Role: Schema.Literals<["user", "assistant"]>;
 /**
- * @since 4.0.0
+ * Type represented by the MCP role schema.
+ *
+ * Valid roles are `"user"` and `"assistant"`.
+ *
  * @category common
+ * @since 4.0.0
  */
 export type Role = typeof Role.Type;
 declare const Annotations_base: Schema.Opaque<Annotations, Schema.Struct<{
@@ -291,8 +368,8 @@ declare const Annotations_base: Schema.Opaque<Annotations, Schema.Struct<{
  * Optional annotations for the client. The client can use annotations to
  * inform how objects are used or displayed
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare class Annotations extends Annotations_base {
 }
@@ -308,8 +385,8 @@ declare const Implementation_base: Schema.Opaque<Implementation, Schema.Struct<{
 /**
  * Describes the name and version of an MCP implementation.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare class Implementation extends Implementation_base {
 }
@@ -351,8 +428,8 @@ declare const ClientCapabilities_base: Schema.Class<ClientCapabilities, Schema.S
  * this schema, but this is not a closed set: any client can define its own,
  * additional capabilities.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare class ClientCapabilities extends ClientCapabilities_base {
 }
@@ -498,8 +575,8 @@ declare const ServerCapabilities_base: Schema.Opaque<ServerCapabilities, Schema.
  * here, in this schema, but this is not a closed set: any server can define
  * its own, additional capabilities.
  *
- * @since 4.0.0
  * @category common
+ * @since 4.0.0
  */
 export declare class ServerCapabilities extends ServerCapabilities_base {
 }
@@ -520,34 +597,50 @@ declare const McpErrorBase_base: Schema.Class<McpErrorBase, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, {}>;
 /**
- * @since 4.0.0
+ * Base schema for MCP and JSON-RPC error objects.
+ *
+ * It contains the numeric error `code`, a concise `message`, and optional
+ * sender-defined `data`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class McpErrorBase extends McpErrorBase_base {
 }
 /**
- * @since 4.0.0
+ * JSON-RPC error code for requests that are not valid request objects.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const INVALID_REQUEST_ERROR_CODE: -32600;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for requests whose method does not exist or is not
+ * available.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const METHOD_NOT_FOUND_ERROR_CODE: -32601;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for invalid method parameters.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const INVALID_PARAMS_ERROR_CODE: -32602;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for internal server errors.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const INTERNAL_ERROR_CODE: -32603;
 /**
- * @since 4.0.0
+ * JSON-RPC error code for invalid JSON that could not be parsed.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const PARSE_ERROR_CODE: -32700;
 declare const ParseError_base: Schema.Class<ParseError, Schema.Struct<{
@@ -565,8 +658,12 @@ declare const ParseError_base: Schema.Class<ParseError, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for invalid JSON that could not be parsed.
+ *
+ * This error uses the standard parse error code `-32700`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class ParseError extends ParseError_base {
 }
@@ -585,8 +682,12 @@ declare const InvalidRequest_base: Schema.Class<InvalidRequest, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for a request object that is not valid.
+ *
+ * This error uses the standard invalid request code `-32600`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class InvalidRequest extends InvalidRequest_base {
 }
@@ -605,8 +706,12 @@ declare const MethodNotFound_base: Schema.Class<MethodNotFound, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for a method that does not exist or is not available.
+ *
+ * This error uses the standard method not found code `-32601`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class MethodNotFound extends MethodNotFound_base {
 }
@@ -625,8 +730,12 @@ declare const InvalidParams_base: Schema.Class<InvalidParams, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for invalid method parameters.
+ *
+ * This error uses the standard invalid params code `-32602`.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class InvalidParams extends InvalidParams_base {
 }
@@ -645,15 +754,23 @@ declare const InternalError_base: Schema.Class<InternalError, Schema.Struct<{
     readonly data: Schema.decodeTo<Schema.optional<Schema.Any>, Schema.optionalKey<Schema.Any>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * MCP/JSON-RPC error for unexpected internal server failures.
+ *
+ * This error uses the standard internal error code `-32603` and includes
+ * `InternalError.notImplemented` for unimplemented handlers.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare class InternalError extends InternalError_base {
     static readonly notImplemented: InternalError;
 }
 /**
- * @since 4.0.0
+ * Schema for MCP protocol errors returned in JSON-RPC failure responses,
+ * including standard protocol errors and custom `McpErrorBase` values.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export declare const McpError: Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>;
 declare const Ping_base: Rpc.Rpc<"ping", Schema.UndefinedOr<typeof RequestMeta>, Schema.Struct<{}>, Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>, never, never>;
@@ -662,8 +779,8 @@ declare const Ping_base: Rpc.Rpc<"ping", Schema.UndefinedOr<typeof RequestMeta>,
  * party is still alive. The receiver must promptly respond, or else may be
  * disconnected.
  *
- * @since 4.0.0
  * @category ping
+ * @since 4.0.0
  */
 export declare class Ping extends Ping_base {
 }
@@ -716,8 +833,8 @@ declare const InitializeResult_base: Schema.Opaque<InitializeResult, Schema.Stru
  * After receiving an initialize request from the client, the server sends this
  * response.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export declare class InitializeResult extends InitializeResult_base {
 }
@@ -761,8 +878,8 @@ declare const Initialize_base: Rpc.Rpc<"initialize", Schema.Struct<{
  * This request is sent from the client to the server when it first connects,
  * asking it to begin initialization.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export declare class Initialize extends Initialize_base {
 }
@@ -771,8 +888,8 @@ declare const InitializedNotification_base: Rpc.Rpc<"notifications/initialized",
  * This notification is sent from the client to the server after initialization
  * has finished.
  *
- * @since 4.0.0
  * @category initialization
+ * @since 4.0.0
  */
 export declare class InitializedNotification extends InitializedNotification_base {
 }
@@ -792,8 +909,14 @@ declare const CancelledNotification_base: Rpc.Rpc<"notifications/cancelled", Sch
     _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, Schema.Void, Schema.Never, never, never>;
 /**
- * @since 4.0.0
+ * Notification sent by either peer to cancel a previously issued request in
+ * the same direction.
+ *
+ * The payload identifies the request to cancel and may include a
+ * human-readable reason.
+ *
  * @category cancellation
+ * @since 4.0.0
  */
 export declare class CancelledNotification extends CancelledNotification_base {
 }
@@ -822,8 +945,8 @@ declare const ProgressNotification_base: Rpc.Rpc<"notifications/progress", Schem
  * An out-of-band notification used to inform the receiver of a progress update
  * for a long-running request.
  *
- * @since 4.0.0
  * @category progress
+ * @since 4.0.0
  */
 export declare class ProgressNotification extends ProgressNotification_base {
 }
@@ -873,8 +996,8 @@ declare const Resource_base: Schema.Class<Resource, Schema.Struct<{
 /**
  * A known resource that the server is capable of reading.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class Resource extends Resource_base {
 }
@@ -915,8 +1038,8 @@ declare const ResourceTemplate_base: Schema.Class<ResourceTemplate, Schema.Struc
 /**
  * A template description for resources available on the server.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ResourceTemplate extends ResourceTemplate_base {
 }
@@ -950,8 +1073,8 @@ declare const ResourceContents_base: Schema.Opaque<ResourceContents, Schema.Stru
 /**
  * The contents of a specific resource or sub-resource.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ResourceContents extends ResourceContents_base {
 }
@@ -995,8 +1118,8 @@ declare const TextResourceContents_base: Schema.Opaque<TextResourceContents, Sch
 /**
  * The contents of a text resource, which can be represented as a string.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class TextResourceContents extends TextResourceContents_base {
 }
@@ -1038,8 +1161,8 @@ declare const BlobResourceContents_base: Schema.Opaque<BlobResourceContents, Sch
 /**
  * The contents of a binary resource, which can be represented as an Uint8Array
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class BlobResourceContents extends BlobResourceContents_base {
 }
@@ -1059,8 +1182,8 @@ declare const ListResourcesResult_base: Schema.Class<ListResourcesResult, Schema
 /**
  * The server's response to a resources/list request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ListResourcesResult extends ListResourcesResult_base {
 }
@@ -1068,8 +1191,8 @@ declare const ListResources_base: Rpc.Rpc<"resources/list", Schema.UndefinedOr<t
 /**
  * Sent from the client to request a list of resources the server has.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ListResources extends ListResources_base {
 }
@@ -1089,8 +1212,8 @@ declare const ListResourceTemplatesResult_base: Schema.Class<ListResourceTemplat
 /**
  * The server's response to a resources/templates/list request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ListResourceTemplatesResult extends ListResourceTemplatesResult_base {
 }
@@ -1098,8 +1221,8 @@ declare const ListResourceTemplates_base: Rpc.Rpc<"resources/templates/list", Sc
 /**
  * Sent from the client to request a list of resource templates the server has.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ListResourceTemplates extends ListResourceTemplates_base {
 }
@@ -1121,8 +1244,8 @@ declare const ReadResourceResult_base: Schema.Opaque<ReadResourceResult, Schema.
 /**
  * The server's response to a resources/read request from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ReadResourceResult extends ReadResourceResult_base {
 }
@@ -1155,8 +1278,8 @@ declare const ReadResource_base: Rpc.Rpc<"resources/read", Schema.Struct<{
 /**
  * Sent from the client to the server, to read a specific resource URI.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ReadResource extends ReadResource_base {
 }
@@ -1166,8 +1289,8 @@ declare const ResourceListChangedNotification_base: Rpc.Rpc<"notifications/resou
  * list of resources it can read from has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class ResourceListChangedNotification extends ResourceListChangedNotification_base {
 }
@@ -1201,8 +1324,8 @@ declare const Subscribe_base: Rpc.Rpc<"resources/subscribe", Schema.Struct<{
  * Sent from the client to request resources/updated notifications from the
  * server whenever a particular resource changes.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class Subscribe extends Subscribe_base {
 }
@@ -1237,8 +1360,8 @@ declare const Unsubscribe_base: Rpc.Rpc<"resources/unsubscribe", Schema.Struct<{
  * notifications from the server. This should follow a previous
  * resources/subscribe request.
  *
- * @since 4.0.0
  * @category resources
+ * @since 4.0.0
  */
 export declare class Unsubscribe extends Unsubscribe_base {
 }
@@ -1250,8 +1373,13 @@ declare const ResourceUpdatedNotification_base: Rpc.Rpc<"notifications/resources
     _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, Schema.Void, Schema.Never, never, never>;
 /**
- * @since 4.0.0
+ * Notification sent by the server when a subscribed resource URI has changed.
+ *
+ * The URI may identify a sub-resource of the resource that the client
+ * originally subscribed to.
+ *
  * @category resources
+ * @since 4.0.0
  */
 export declare class ResourceUpdatedNotification extends ResourceUpdatedNotification_base {
 }
@@ -1287,8 +1415,8 @@ declare const PromptArgument_base: Schema.Opaque<PromptArgument, Schema.Struct<{
 /**
  * Describes an argument that a prompt can accept.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class PromptArgument extends PromptArgument_base {
 }
@@ -1310,8 +1438,8 @@ declare const Prompt_base: Schema.Class<Prompt, Schema.Struct<{
 /**
  * A prompt or prompt template that the server offers.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class Prompt extends Prompt_base {
 }
@@ -1339,8 +1467,8 @@ declare const TextContent_base: Schema.Opaque<TextContent, Schema.Struct<{
 /**
  * Text provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class TextContent extends TextContent_base {
 }
@@ -1378,8 +1506,8 @@ declare const ImageContent_base: Schema.Opaque<ImageContent, Schema.Struct<{
 /**
  * An image provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class ImageContent extends ImageContent_base {
 }
@@ -1417,8 +1545,8 @@ declare const AudioContent_base: Schema.Opaque<AudioContent, Schema.Struct<{
 /**
  * Audio provided to or from an LLM.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class AudioContent extends AudioContent_base {
 }
@@ -1443,8 +1571,8 @@ declare const EmbeddedResource_base: Schema.Opaque<EmbeddedResource, Schema.Stru
  * It is up to the client how best to render embedded resources for the benefit
  * of the LLM and/or the user.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class EmbeddedResource extends EmbeddedResource_base {
 }
@@ -1540,14 +1668,17 @@ declare const ResourceLink_base: Schema.Opaque<ResourceLink, Schema.Struct<{
  *
  * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class ResourceLink extends ResourceLink_base {
 }
 /**
- * @since 4.0.0
+ * Union of MCP content blocks that can appear in prompt messages or tool
+ * results, including text, media, embedded resources, and resource links.
+ *
  * @category prompts
+ * @since 4.0.0
  */
 export declare const ContentBlock: Schema.Union<readonly [typeof TextContent, typeof ImageContent, typeof AudioContent, typeof EmbeddedResource, typeof ResourceLink]>;
 declare const PromptMessage_base: Schema.Opaque<PromptMessage, Schema.Struct<{
@@ -1563,8 +1694,8 @@ declare const PromptMessage_base: Schema.Opaque<PromptMessage, Schema.Struct<{
  * This is similar to `SamplingMessage`, but also supports the embedding of
  * resources from the MCP server.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class PromptMessage extends PromptMessage_base {
 }
@@ -1584,8 +1715,8 @@ declare const ListPromptsResult_base: Schema.Class<ListPromptsResult, Schema.Str
 /**
  * The server's response to a prompts/list request from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class ListPromptsResult extends ListPromptsResult_base {
 }
@@ -1594,8 +1725,8 @@ declare const ListPrompts_base: Rpc.Rpc<"prompts/list", Schema.UndefinedOr<typeo
  * Sent from the client to request a list of prompts and prompt templates the
  * server has.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class ListPrompts extends ListPrompts_base {
 }
@@ -1614,8 +1745,8 @@ declare const GetPromptResult_base: Schema.Class<GetPromptResult, Schema.Struct<
 /**
  * The server's response to a prompts/get request from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class GetPromptResult extends GetPromptResult_base {
 }
@@ -1652,8 +1783,8 @@ declare const GetPrompt_base: Rpc.Rpc<"prompts/get", Schema.Struct<{
 /**
  * Used by the client to get a prompt provided by the server.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class GetPrompt extends GetPrompt_base {
 }
@@ -1663,8 +1794,8 @@ declare const PromptListChangedNotification_base: Rpc.Rpc<"notifications/prompts
  * the list of prompts it offers has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category prompts
+ * @since 4.0.0
  */
 export declare class PromptListChangedNotification extends PromptListChangedNotification_base {
 }
@@ -1755,8 +1886,8 @@ declare const ToolAnnotations_base: Schema.Opaque<ToolAnnotations, Schema.Struct
  * Clients should never make tool use decisions based on ToolAnnotations
  * received from untrusted servers.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class ToolAnnotations extends ToolAnnotations_base {
 }
@@ -1791,8 +1922,8 @@ declare const Tool_base: Schema.Class<Tool, Schema.Struct<{
 /**
  * Definition for a tool the client can call.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class Tool extends Tool_base {
 }
@@ -1812,8 +1943,8 @@ declare const ListToolsResult_base: Schema.Class<ListToolsResult, Schema.Struct<
 /**
  * The server's response to a tools/list request from the client.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class ListToolsResult extends ListToolsResult_base {
 }
@@ -1821,8 +1952,8 @@ declare const ListTools_base: Rpc.Rpc<"tools/list", Schema.UndefinedOr<typeof Pa
 /**
  * Sent from the client to request a list of tools the server has.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class ListTools extends ListTools_base {
 }
@@ -1853,8 +1984,8 @@ declare const CallToolResult_base: Schema.Class<CallToolResult, Schema.Struct<{
  * server does not support tool calls, or any other exceptional conditions,
  * should be reported as an MCP error response.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class CallToolResult extends CallToolResult_base {
 }
@@ -1884,8 +2015,8 @@ declare const CallTool_base: Rpc.Rpc<"tools/call", Schema.Struct<{
 /**
  * Used by the client to invoke a tool provided by the server.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class CallTool extends CallTool_base {
 }
@@ -1895,8 +2026,8 @@ declare const ToolListChangedNotification_base: Rpc.Rpc<"notifications/tools/lis
  * the list of tools it offers has changed. This may be issued by servers
  * without any previous subscription from the client.
  *
- * @since 4.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare class ToolListChangedNotification extends ToolListChangedNotification_base {
 }
@@ -1906,8 +2037,8 @@ export declare class ToolListChangedNotification extends ToolListChangedNotifica
  * These map to syslog message severities, as specified in RFC-5424:
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
  *
- * @since 4.0.0
  * @category logging
+ * @since 4.0.0
  */
 export declare const LoggingLevel: Schema.Literals<[
     "debug",
@@ -1925,8 +2056,8 @@ export declare const LoggingLevel: Schema.Literals<[
  * These map to syslog message severities, as specified in RFC-5424:
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
  *
- * @since 4.0.0
  * @category logging
+ * @since 4.0.0
  */
 export type LoggingLevel = typeof LoggingLevel.Type;
 declare const SetLevel_base: Rpc.Rpc<"logging/setLevel", Schema.Struct<{
@@ -1959,8 +2090,8 @@ declare const SetLevel_base: Rpc.Rpc<"logging/setLevel", Schema.Struct<{
 /**
  * A request from the client to the server, to enable or adjust logging.
  *
- * @since 4.0.0
  * @category logging
+ * @since 4.0.0
  */
 export declare class SetLevel extends SetLevel_base {
 }
@@ -1985,8 +2116,13 @@ declare const LoggingMessageNotification_base: Rpc.Rpc<"notifications/message",
     readonly _meta: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>, never, never>;
 }>, Schema.Void, Schema.Never, never, never>;
 /**
- * @since 4.0.0
+ * Server notification carrying a log message for the client.
+ *
+ * The notification includes the severity level, optional logger name, and
+ * JSON-serializable log data.
+ *
  * @category logging
+ * @since 4.0.0
  */
 export declare class LoggingMessageNotification extends LoggingMessageNotification_base {
 }
@@ -2000,8 +2136,8 @@ declare const SamplingMessage_base: Schema.Opaque<SamplingMessage, Schema.Struct
 /**
  * Describes a message issued to or received from an LLM API.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export declare class SamplingMessage extends SamplingMessage_base {
 }
@@ -2040,8 +2176,8 @@ declare const ModelHint_base: Schema.Opaque<ModelHint, Schema.Struct<{
  * Keys not declared here are currently left unspecified by the spec and are up
  * to the client to interpret.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export declare class ModelHint extends ModelHint_base {
 }
@@ -2088,8 +2224,8 @@ declare const ModelPreferences_base: Schema.Class<ModelPreferences, Schema.Struc
  * up to the client to decide how to interpret these preferences and how to
  * balance them against other considerations.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export declare class ModelPreferences extends ModelPreferences_base {
 }
@@ -2109,8 +2245,8 @@ declare const CreateMessageResult_base: Schema.Class<CreateMessageResult, Schema
  * allow them to inspect the response (human in the loop) and decide whether to
  * allow the server to see it.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export declare class CreateMessageResult extends CreateMessageResult_base {
 }
@@ -2150,8 +2286,8 @@ declare const CreateMessage_base: Rpc.Rpc<"sampling/createMessage", Schema.Struc
  * user before beginning sampling, to allow them to inspect the request (human
  * in the loop) and decide whether to approve it.
  *
- * @since 4.0.0
  * @category sampling
+ * @since 4.0.0
  */
 export declare class CreateMessage extends CreateMessage_base {
 }
@@ -2171,8 +2307,8 @@ declare const ResourceReference_base: Schema.Opaque<ResourceReference, Schema.St
 /**
  * A reference to a resource or resource template definition.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export declare class ResourceReference extends ResourceReference_base {
 }
@@ -2194,8 +2330,8 @@ declare const PromptReference_base: Schema.Opaque<PromptReference, Schema.Struct
 /**
  * Identifies a prompt.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export declare class PromptReference extends PromptReference_base {
 }
@@ -2237,11 +2373,13 @@ declare const CompleteResult_base: Schema.Opaque<CompleteResult, Schema.Struct<{
 /**
  * The server's response to a completion/complete request
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export declare class CompleteResult extends CompleteResult_base {
     /**
+     * Empty completion result used when a completion request has no values.
+     *
      * @since 4.0.0
      */
     static readonly empty: CompleteResult;
@@ -2274,8 +2412,8 @@ declare const Complete_base: Rpc.Rpc<"completion/complete", Schema.Struct<{
 /**
  * A request from the client to the server, to ask for completion options.
  *
- * @since 4.0.0
  * @category autocomplete
+ * @since 4.0.0
  */
 export declare class Complete extends Complete_base {
 }
@@ -2296,8 +2434,8 @@ declare const Root_base: Schema.Class<Root, Schema.Struct<{
 /**
  * Represents a root directory or file that the server can operate on.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export declare class Root extends Root_base {
 }
@@ -2309,8 +2447,8 @@ declare const ListRootsResult_base: Schema.Class<ListRootsResult, Schema.Struct<
  * contains an array of Root objects, each representing a root directory or file
  * that the server can operate on.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export declare class ListRootsResult extends ListRootsResult_base {
 }
@@ -2326,8 +2464,8 @@ declare const ListRoots_base: Rpc.Rpc<"roots/list", Schema.UndefinedOr<typeof Re
  * system structure or access specific locations that the client has permission
  * to read from.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export declare class ListRoots extends ListRoots_base {
 }
@@ -2338,8 +2476,8 @@ declare const RootsListChangedNotification_base: Rpc.Rpc<"notifications/roots/li
  * removes, or modifies any root. The server should then request an updated list
  * of roots using the ListRootsRequest.
  *
- * @since 4.0.0
  * @category roots
+ * @since 4.0.0
  */
 export declare class RootsListChangedNotification extends RootsListChangedNotification_base {
 }
@@ -2365,8 +2503,8 @@ declare const ElicitAcceptResult_base: Schema.Class<ElicitAcceptResult, Schema.S
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export declare class ElicitAcceptResult extends ElicitAcceptResult_base {
 }
@@ -2387,16 +2525,16 @@ declare const ElicitDeclineResult_base: Schema.Class<ElicitDeclineResult, Schema
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export declare class ElicitDeclineResult extends ElicitDeclineResult_base {
 }
 /**
  * The client's response to an elicitation request
  *
- * @since 4.0.0
  * @category elicitation
+ * @since 4.0.0
  */
 export declare const ElicitResult: Schema.Union<readonly [typeof ElicitAcceptResult, typeof ElicitDeclineResult]>;
 declare const Elicit_base: Rpc.Rpc<"elicitation/create", Schema.Struct<{
@@ -2412,8 +2550,14 @@ declare const Elicit_base: Rpc.Rpc<"elicitation/create", Schema.Struct<{
     requestedSchema: Schema.Any;
 }>, Schema.Union<readonly [typeof ElicitAcceptResult, typeof ElicitDeclineResult]>, Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>, never, never>;
 /**
- * @since 4.0.0
+ * Request sent by the server asking the client to collect structured input
+ * from the user.
+ *
+ * The client responds with accepted content, an explicit decline, or a
+ * cancellation.
+ *
  * @category elicitation
+ * @since 4.0.0
  */
 export declare class Elicit extends Elicit_base {
 }
@@ -2434,8 +2578,14 @@ declare const ElicitationDeclined_base: Schema.Class<ElicitationDeclined, Schema
     readonly cause: Schema.decodeTo<Schema.optional<Schema.Defect>, Schema.optionalKey<Schema.Defect>, never, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
- * @since 4.0.0
+ * Error raised when an MCP elicitation request is declined or fails before
+ * accepted content is returned.
+ *
+ * The error stores the original elicitation request and, when available, the
+ * underlying cause.
+ *
  * @category elicitation
+ * @since 4.0.0
  */
 export declare class ElicitationDeclined extends ElicitationDeclined_base {
 }
@@ -2445,21 +2595,32 @@ declare const McpServerClient_base: Context.ServiceClass<McpServerClient, "effec
     readonly getClient: Effect.Effect<RpcClient.RpcClient<RpcGroup.Rpcs<typeof ServerRequestRpcs>, RpcClientError>, never, Scope.Scope>;
 }>;
 /**
- * @since 4.0.0
+ * Service available while handling an MCP client request.
+ *
+ * It exposes the current client id, the client's initialize payload, and a
+ * scoped RPC client for server-initiated requests back to that client.
+ *
  * @category client
+ * @since 4.0.0
  */
 export declare class McpServerClient extends McpServerClient_base {
 }
 declare const McpServerClientMiddleware_base: RpcMiddleware.ServiceClass<McpServerClientMiddleware, "effect/ai/McpSchema/McpServerClientMiddleware", McpServerClient, Schema.Never, never, never, false>;
 /**
- * @since 4.0.0
+ * RPC middleware that provides `McpServerClient` to handlers for initialized
+ * MCP clients.
+ *
  * @category middleware
+ * @since 4.0.0
  */
 export declare class McpServerClientMiddleware extends McpServerClientMiddleware_base {
 }
 /**
- * @since 4.0.0
+ * Encoded JSON-RPC request message for an RPC in `Group`, including the request
+ * id, method, and encoded payload.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type RequestEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> extends infer Rpc ? Rpc extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware> ? {
     readonly _tag: "Request";
@@ -2468,8 +2629,11 @@ export type RequestEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> ex
     readonly payload: _Payload["Encoded"];
 } : never : never;
 /**
- * @since 4.0.0
+ * Encoded notification message for an RPC in `Group`, including the method and
+ * encoded payload without a request id.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type NotificationEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> extends infer Rpc ? Rpc extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware> ? {
     readonly _tag: "Notification";
@@ -2477,8 +2641,11 @@ export type NotificationEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Grou
     readonly payload: _Payload["Encoded"];
 } : never : never;
 /**
- * @since 4.0.0
+ * Encoded success response for an RPC in `Group`, containing the original
+ * request id and encoded result.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type SuccessEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> extends infer Rpc ? Rpc extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware> ? {
     readonly _tag: "Success";
@@ -2486,8 +2653,11 @@ export type SuccessEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> ex
     readonly result: _Success["Encoded"];
 } : never : never;
 /**
- * @since 4.0.0
+ * Encoded failure response for an RPC in `Group`, containing the original
+ * request id and encoded error.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type FailureEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<Group> extends infer Rpc ? Rpc extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware> ? {
     readonly _tag: "Failure";
@@ -2707,26 +2877,39 @@ declare const ClientRequestRpcs_base: RpcGroup.RpcGroup<Rpc.Rpc<"ping", Schema.U
     }>>;
 }>, typeof CompleteResult, Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>, typeof McpServerClientMiddleware, never>>;
 /**
- * @since 4.0.0
+ * RPC group for requests that MCP clients send to the server.
+ *
+ * The group includes initialization, resource, prompt, tool, logging,
+ * completion, and ping requests, and installs `McpServerClientMiddleware` for
+ * handlers.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export declare class ClientRequestRpcs extends ClientRequestRpcs_base {
 }
 /**
- * @since 4.0.0
+ * Encoded union of all client-to-server MCP request messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>;
 declare const ClientNotificationRpcs_base: RpcGroup.RpcGroup<typeof InitializedNotification | typeof CancelledNotification | typeof ProgressNotification | typeof RootsListChangedNotification>;
 /**
- * @since 4.0.0
+ * RPC group for notifications that MCP clients send to the server, such as
+ * cancellation, progress, initialization completion, and roots list changes.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export declare class ClientNotificationRpcs extends ClientNotificationRpcs_base {
 }
 /**
- * @since 4.0.0
+ * Encoded union of all client-to-server MCP notification messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>;
 declare const ClientRpcs_base: RpcGroup.RpcGroup<typeof InitializedNotification | typeof CancelledNotification | typeof ProgressNotification | typeof RootsListChangedNotification | Rpc.Rpc<"ping", Schema.UndefinedOr<typeof RequestMeta>, Schema.Struct<{}>, Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>, typeof McpServerClientMiddleware, never> | Rpc.Rpc<"initialize", Schema.Struct<{
@@ -2942,79 +3125,116 @@ declare const ClientRpcs_base: RpcGroup.RpcGroup<typeof InitializedNotification
     }>>;
 }>, typeof CompleteResult, Schema.Union<readonly [typeof ParseError, typeof InvalidRequest, typeof MethodNotFound, typeof InvalidParams, typeof InternalError, typeof McpErrorBase]>, typeof McpServerClientMiddleware, never>>;
 /**
- * @since 4.0.0
+ * RPC group combining all client-to-server MCP requests and notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export declare class ClientRpcs extends ClientRpcs_base {
 }
 /**
- * @since 4.0.0
+ * Encoded success response sent by a client for a server-initiated request.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>;
 /**
- * @since 4.0.0
+ * Encoded failure response sent by a client for a server-initiated request.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>;
 declare const ServerRequestRpcs_base: RpcGroup.RpcGroup<typeof Ping | typeof CreateMessage | typeof ListRoots | typeof Elicit>;
 /**
- * @since 4.0.0
+ * RPC group for requests that an MCP server can send to a client, including
+ * ping, sampling, roots listing, and elicitation.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export declare class ServerRequestRpcs extends ServerRequestRpcs_base {
 }
 /**
- * @since 4.0.0
+ * Encoded union of all server-to-client MCP request messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>;
 declare const ServerNotificationRpcs_base: RpcGroup.RpcGroup<typeof CancelledNotification | typeof ProgressNotification | typeof ResourceListChangedNotification | typeof ResourceUpdatedNotification | typeof PromptListChangedNotification | typeof ToolListChangedNotification | typeof LoggingMessageNotification>;
 /**
- * @since 4.0.0
+ * RPC group for notifications that an MCP server can send to a client,
+ * including cancellation, progress, logging, and list or resource update
+ * notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export declare class ServerNotificationRpcs extends ServerNotificationRpcs_base {
 }
 /**
- * @since 4.0.0
+ * Encoded union of all server-to-client MCP notification messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>;
 /**
- * @since 4.0.0
+ * Encoded success response sent by the server for a client-initiated request.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>;
 /**
- * @since 4.0.0
+ * Encoded failure response sent by the server for a client-initiated request.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>;
 /**
- * @since 4.0.0
+ * Encoded server response to a client request, either success or failure.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded;
 /**
- * @since 4.0.0
+ * Encoded MCP messages accepted from a client by the server protocol: client
+ * requests and client notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded;
 /**
- * @since 4.0.0
+ * Encoded MCP messages emitted by the server protocol to a client: server
+ * responses and server notifications.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded;
 declare const ParamSchemaTypeId = "~effect/ai/McpSchema/ParamSchema";
 /**
- * @since 4.0.0
+ * Returns `true` when a schema was created with `param` and therefore carries
+ * a resource URI template parameter name.
+ *
  * @category parameters
+ * @since 4.0.0
  */
 export declare function isParam(schema: Schema.Top): schema is Param<string, Schema.Top>;
 /**
- * @since 4.0.0
+ * Schema wrapper used for resource URI template parameters.
+ *
+ * A `Param` behaves like the wrapped schema while carrying the parameter name
+ * used for template compilation and completion lookup.
+ *
  * @category parameters
+ * @since 4.0.0
  */
 export interface Param<Name extends string, S extends Schema.Top> extends Schema.Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], Param<Name, S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
     readonly "Rebuild": Param<Name, S>;
@@ -3025,8 +3245,8 @@ export interface Param<Name extends string, S extends Schema.Top> extends Schema
 /**
  * Helper to create a param for a resource URI template.
  *
- * @since 4.0.0
  * @category parameters
+ * @since 4.0.0
  */
 export declare function param<const Name extends string, S extends Schema.Top>(name: Name, schema: S): Param<Name, S>;
 declare const EnabledWhen_base: Context.ServiceClass<EnabledWhen, "effect/unstable/ai/McpSchema/EnabledWhen", Predicate.Predicate<{
@@ -3041,8 +3261,8 @@ declare const EnabledWhen_base: Context.ServiceClass<EnabledWhen, "effect/unstab
  * Annotation to conditionally enable or disable tools based on client
  * information.
  *
- * @since 4.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare class EnabledWhen extends EnabledWhen_base {
 }