effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/unstable/ai/McpSchema.js

@@ -77,17 +77,17 @@ export const optional = schema => Schema.optionalKey(schema).pipe(Schema.decodeT
 // Common
 // =============================================================================
 /**
- * A uniquely identifying ID for a request in JSON-RPC.
+ * Schema for JSON-RPC request identifiers, allowing string or number ids.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export const RequestId = /*#__PURE__*/Schema.Union([Schema.String, Schema.Number]);
 /**
- * A progress token, used to associate progress notifications with the original
- * request.
+ * Schema for MCP progress tokens that associate progress notifications with the
+ * original request.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export const ProgressToken = /*#__PURE__*/Schema.Union([Schema.String, Schema.Number]);
@@ -99,7 +99,7 @@ export const ProgressToken = /*#__PURE__*/Schema.Union([Schema.String, Schema.Nu
  * Request metadata may include a progress token that asks the receiver to send
  * out-of-band progress notifications for the request.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class RequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -122,7 +122,7 @@ export class RequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
  * The `_meta` field is reserved for protocol, extension, or implementation
  * metadata attached to a result.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class ResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -140,7 +140,7 @@ export class ResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema
  * The `_meta` field is reserved for protocol, extension, or implementation
  * metadata attached to a notification.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class NotificationMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -151,9 +151,9 @@ export class NotificationMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 })) {}
 /**
- * An opaque token used to represent a cursor for pagination.
+ * Schema for opaque cursor tokens used in pagination.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export const Cursor = Schema.String;
@@ -165,7 +165,7 @@ export const Cursor = Schema.String;
  * It includes the base request metadata fields plus an optional cursor
  * indicating where the server should continue listing results.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class PaginatedRequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -184,7 +184,7 @@ export class PaginatedRequestMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
  * It includes the base result metadata fields plus an optional `nextCursor`,
  * which indicates that more results may be available.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class PaginatedResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -196,17 +196,21 @@ export class PaginatedResultMeta extends /*#__PURE__*/Schema.Opaque()(/*#__PURE_
   nextCursor: /*#__PURE__*/optional(Cursor)
 })) {}
 /**
- * The sender or recipient of messages and data in a conversation.
+ * Schema for MCP conversation roles, allowing user and assistant.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export const Role = /*#__PURE__*/Schema.Literals(["user", "assistant"]);
 /**
- * Optional annotations for the client. The client can use annotations to
- * inform how objects are used or displayed
+ * Schema for optional client-facing annotations on MCP objects.
+ *
+ * **When to use**
+ *
+ * Use to describe intended audience and priority metadata for objects shown or
+ * processed by a client.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class Annotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -232,7 +236,7 @@ export class Annotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
 /**
  * Describes the name and version of an MCP implementation.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class Implementation extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -241,11 +245,19 @@ export class Implementation extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
   version: Schema.String
 })) {}
 /**
- * Capabilities a client may support. Known capabilities are defined here, in
- * this schema, but this is not a closed set: any client can define its own,
- * additional capabilities.
+ * Describes capabilities advertised by an MCP client.
+ *
+ * **When to use**
+ *
+ * Use to describe which optional MCP features a client supports during
+ * initialization.
  *
- * @category common
+ * **Details**
+ *
+ * Known capabilities are represented by this schema, but the capability set is
+ * open and clients may define additional capabilities.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export class ClientCapabilities extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ClientCapabilities")({
@@ -277,11 +289,19 @@ export class ClientCapabilities extends /*#__PURE__*/Schema.Class("@effect/ai/Mc
   elicitation: /*#__PURE__*/optional(/*#__PURE__*/Schema.Struct({}))
 }) {}
 /**
- * Capabilities that a server may support. Known capabilities are defined
- * here, in this schema, but this is not a closed set: any server can define
- * its own, additional capabilities.
+ * Describes capabilities advertised by an MCP server.
+ *
+ * **When to use**
+ *
+ * Use to describe which optional MCP features a server supports during
+ * initialization.
+ *
+ * **Details**
  *
- * @category common
+ * Known capabilities are represented by this schema, but the capability set is
+ * open and servers may define additional capabilities.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export class ServerCapabilities extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -338,14 +358,14 @@ export class ServerCapabilities extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__
 // Errors
 // =============================================================================
 /**
- * Base schema for MCP and JSON-RPC error objects.
+ * Schema for MCP and JSON-RPC error objects.
  *
  * **Details**
  *
  * It contains the numeric error `code`, a concise `message`, and optional
  * sender-defined `data`.
  *
- * @category errors
+ * @category schemas
  * @since 4.0.0
  */
 export class McpErrorBase extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/McpErrorBase")({
@@ -365,44 +385,75 @@ export class McpErrorBase extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchem
   data: /*#__PURE__*/optional(Schema.Any)
 }) {}
 /**
- * JSON-RPC error code for requests that are not valid request objects.
+ * Represents the JSON-RPC error code for requests that are not valid request objects.
  *
- * @category errors
+ * **When to use**
+ *
+ * Use when you need the JSON-RPC error code for requests that are not valid
+ * request objects.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const INVALID_REQUEST_ERROR_CODE = -32600;
 /**
- * JSON-RPC error code for requests whose method does not exist or is not
+ * Represents the JSON-RPC error code for requests whose method does not exist or is not
  * available.
  *
- * @category errors
+ * **When to use**
+ *
+ * Use when you need the JSON-RPC error code for requests whose method does not
+ * exist or is not available.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const METHOD_NOT_FOUND_ERROR_CODE = -32601;
 /**
- * JSON-RPC error code for invalid method parameters.
+ * Represents the JSON-RPC error code for invalid method parameters.
  *
- * @category errors
+ * **When to use**
+ *
+ * Use when you need the JSON-RPC error code for invalid method parameters.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const INVALID_PARAMS_ERROR_CODE = -32602;
 /**
- * JSON-RPC error code for internal server errors.
+ * Represents the JSON-RPC error code for internal server errors.
  *
- * @category errors
+ * **When to use**
+ *
+ * Use when you need the JSON-RPC error code for internal server errors.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const INTERNAL_ERROR_CODE = -32603;
 /**
- * JSON-RPC error code for invalid JSON that could not be parsed.
+ * Represents the JSON-RPC error code for invalid JSON that could not be parsed.
  *
- * @category errors
+ * **When to use**
+ *
+ * Use when you need the JSON-RPC error code for invalid JSON that could not be
+ * parsed.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const PARSE_ERROR_CODE = -32700;
 /**
- * MCP/JSON-RPC error for invalid JSON that could not be parsed. This error
- * uses the standard parse error code `-32700`.
+ * Represents an MCP/JSON-RPC error for invalid JSON that could not be parsed.
+ *
+ * **When to use**
+ *
+ * Use to report a JSON parse failure before a valid JSON-RPC request object is
+ * available.
+ *
+ * **Details**
+ *
+ * Uses the standard JSON-RPC parse error code `-32700`.
  *
  * @category errors
  * @since 4.0.0
@@ -413,8 +464,16 @@ export class ParseError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/McpSch
   code: /*#__PURE__*/Schema.tag(PARSE_ERROR_CODE)
 }) {}
 /**
- * MCP/JSON-RPC error for a request object that is not valid. This error uses
- * the standard invalid request code `-32600`.
+ * Represents an MCP/JSON-RPC error for a request object that is not valid.
+ *
+ * **When to use**
+ *
+ * Use to report a syntactically parsed JSON-RPC request that is not a valid
+ * request object.
+ *
+ * **Details**
+ *
+ * Uses the standard JSON-RPC invalid request code `-32600`.
  *
  * @category errors
  * @since 4.0.0
@@ -425,8 +484,15 @@ export class InvalidRequest extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mc
   code: /*#__PURE__*/Schema.tag(INVALID_REQUEST_ERROR_CODE)
 }) {}
 /**
- * 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`.
+ * Represents an MCP/JSON-RPC error for an unavailable method.
+ *
+ * **When to use**
+ *
+ * Use to report a JSON-RPC method that does not exist or is not available.
+ *
+ * **Details**
+ *
+ * Uses the standard JSON-RPC method-not-found code `-32601`.
  *
  * @category errors
  * @since 4.0.0
@@ -437,8 +503,16 @@ export class MethodNotFound extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mc
   code: /*#__PURE__*/Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
 }) {}
 /**
- * MCP/JSON-RPC error for invalid method parameters. This error uses the
- * standard invalid params code `-32602`.
+ * Represents an MCP/JSON-RPC error for invalid method parameters.
+ *
+ * **When to use**
+ *
+ * Use to report a request whose method parameters do not match the method
+ * schema.
+ *
+ * **Details**
+ *
+ * Uses the standard JSON-RPC invalid params code `-32602`.
  *
  * @category errors
  * @since 4.0.0
@@ -449,8 +523,16 @@ export class InvalidParams extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Mcp
   code: /*#__PURE__*/Schema.tag(INVALID_PARAMS_ERROR_CODE)
 }) {}
 /**
- * MCP/JSON-RPC error for unexpected internal server failures. This error uses
- * the standard internal error code `-32603` and includes
+ * Represents an MCP/JSON-RPC error for unexpected internal server failures.
+ *
+ * **When to use**
+ *
+ * Use to report an unexpected server-side failure while handling a valid
+ * request.
+ *
+ * **Details**
+ *
+ * Uses the standard JSON-RPC internal error code `-32603` and includes
  * `InternalError.notImplemented` for unimplemented handlers.
  *
  * @category errors
@@ -477,9 +559,15 @@ export const McpError = /*#__PURE__*/Schema.Union([ParseError, InvalidRequest, M
 // Ping
 // =============================================================================
 /**
- * A ping, issued by either the server or the client, to check that the other
- * party is still alive. The receiver must promptly respond, or else may be
- * disconnected.
+ * Represents an MCP ping request used to check whether the peer is still alive.
+ *
+ * **When to use**
+ *
+ * Use to implement client or server liveness checks.
+ *
+ * **Details**
+ *
+ * The receiver should respond promptly; otherwise the sender may disconnect.
  *
  * @category ping
  * @since 4.0.0
@@ -493,8 +581,7 @@ export class Ping extends /*#__PURE__*/Rpc.make("ping", {
 // Initialization
 // =============================================================================
 /**
- * After receiving an initialize request from the client, the server sends this
- * response.
+ * Schema for the server's response to an initialize request from the client.
  *
  * @category initialization
  * @since 4.0.0
@@ -519,8 +606,8 @@ export class InitializeResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
   instructions: /*#__PURE__*/optional(Schema.String)
 })) {}
 /**
- * This request is sent from the client to the server when it first connects,
- * asking it to begin initialization.
+ * Sent from the client to the server when it first connects, asking it to begin
+ * initialization.
  *
  * @category initialization
  * @since 4.0.0
@@ -548,8 +635,7 @@ export class Initialize extends /*#__PURE__*/Rpc.make("initialize", {
   }
 }) {}
 /**
- * This notification is sent from the client to the server after initialization
- * has finished.
+ * Sent from the client to the server after initialization has finished.
  *
  * @category initialization
  * @since 4.0.0
@@ -561,8 +647,8 @@ export class InitializedNotification extends /*#__PURE__*/Rpc.make("notification
 // Cancellation
 // =============================================================================
 /**
- * Notification sent by either peer to cancel a previously issued request in
- * the same direction.
+ * Sent from either peer to cancel a previously issued request in the same
+ * direction.
  *
  * **Details**
  *
@@ -593,8 +679,7 @@ export class CancelledNotification extends /*#__PURE__*/Rpc.make("notifications/
 // Progress
 // =============================================================================
 /**
- * An out-of-band notification used to inform the receiver of a progress update
- * for a long-running request.
+ * Sent from either peer to report progress for a long-running request.
  *
  * @category progress
  * @since 4.0.0
@@ -626,7 +711,7 @@ export class ProgressNotification extends /*#__PURE__*/Rpc.make("notifications/p
 // Resources
 // =============================================================================
 /**
- * A known resource that the server is capable of reading.
+ * Schema for a known resource that the server is capable of reading.
  *
  * @category resources
  * @since 4.0.0
@@ -675,7 +760,7 @@ export class Resource extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Re
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 }) {}
 /**
- * A template description for resources available on the server.
+ * Schema for a template description of resources available on the server.
  *
  * @category resources
  * @since 4.0.0
@@ -715,7 +800,7 @@ export class ResourceTemplate extends /*#__PURE__*/Schema.Class("@effect/ai/McpS
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 }) {}
 /**
- * The contents of a specific resource or sub-resource.
+ * Schema for the contents of a specific resource or sub-resource.
  *
  * @category resources
  * @since 4.0.0
@@ -735,7 +820,7 @@ export class ResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 })) {}
 /**
- * The contents of a text resource, which can be represented as a string.
+ * Schema for text resource contents represented as a string.
  *
  * @category resources
  * @since 4.0.0
@@ -749,7 +834,7 @@ export class TextResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
   text: Schema.String
 })) {}
 /**
- * The contents of a binary resource, which can be represented as an Uint8Array
+ * Schema for binary resource contents represented as a `Uint8Array`.
  *
  * @category resources
  * @since 4.0.0
@@ -762,7 +847,7 @@ export class BlobResourceContents extends /*#__PURE__*/Schema.Opaque()(/*#__PURE
   blob: Schema.Uint8Array
 })) {}
 /**
- * The server's response to a resources/list request from the client.
+ * Schema for the server's response to a resources/list request from the client.
  *
  * @category resources
  * @since 4.0.0
@@ -783,7 +868,8 @@ export class ListResources extends /*#__PURE__*/Rpc.make("resources/list", {
   payload: /*#__PURE__*/Schema.UndefinedOr(PaginatedRequestMeta)
 }) {}
 /**
- * The server's response to a resources/templates/list request from the client.
+ * Schema for the server's response to a resources/templates/list request from
+ * the client.
  *
  * @category resources
  * @since 4.0.0
@@ -804,7 +890,7 @@ export class ListResourceTemplates extends /*#__PURE__*/Rpc.make("resources/temp
   payload: /*#__PURE__*/Schema.UndefinedOr(PaginatedRequestMeta)
 }) {}
 /**
- * The server's response to a resources/read request from the client.
+ * Schema for the server's response to a resources/read request from the client.
  *
  * @category resources
  * @since 4.0.0
@@ -832,9 +918,15 @@ export class ReadResource extends /*#__PURE__*/Rpc.make("resources/read", {
   }
 }) {}
 /**
- * An optional notification from the server to the client, informing it that the
- * list of resources it can read from has changed. This may be issued by servers
- * without any previous subscription from the client.
+ * Represents a notification that the server's resource list changed.
+ *
+ * **When to use**
+ *
+ * Use to notify clients that `resources/list` should be requested again.
+ *
+ * **Details**
+ *
+ * Servers may send this notification without a previous client subscription.
  *
  * @category resources
  * @since 4.0.0
@@ -880,7 +972,7 @@ export class Unsubscribe extends /*#__PURE__*/Rpc.make("resources/unsubscribe",
   }
 }) {}
 /**
- * Notification sent by the server when a subscribed resource URI has changed.
+ * Sent from the server when a subscribed resource URI has changed.
  *
  * **Details**
  *
@@ -905,7 +997,7 @@ export class ResourceUpdatedNotification extends /*#__PURE__*/Rpc.make("notifica
 /**
  * Describes an argument that a prompt can accept.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class PromptArgument extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -924,9 +1016,9 @@ export class PromptArgument extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
   required: /*#__PURE__*/optional(Schema.Boolean)
 })) {}
 /**
- * A prompt or prompt template that the server offers.
+ * Represents a prompt or prompt template that the server offers.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class Prompt extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Prompt")({
@@ -945,9 +1037,9 @@ export class Prompt extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Prom
   arguments: /*#__PURE__*/optional(/*#__PURE__*/Schema.Array(PromptArgument))
 }) {}
 /**
- * Text provided to or from an LLM.
+ * Represents text content provided to or from an LLM.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class TextContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -962,9 +1054,9 @@ export class TextContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schem
   annotations: /*#__PURE__*/optional(Annotations)
 })) {}
 /**
- * An image provided to or from an LLM.
+ * Represents image content provided to or from an LLM.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class ImageContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -984,9 +1076,9 @@ export class ImageContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sche
   annotations: /*#__PURE__*/optional(Annotations)
 })) {}
 /**
- * Audio provided to or from an LLM.
+ * Represents audio content provided to or from an LLM.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class AudioContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -1006,14 +1098,14 @@ export class AudioContent extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sche
   annotations: /*#__PURE__*/optional(Annotations)
 })) {}
 /**
- * The contents of a resource, embedded into a prompt or tool call result.
+ * Represents resource contents embedded into a prompt or tool call result.
  *
  * **Details**
  *
  * It is up to the client how best to render embedded resources for the benefit
  * of the LLM and/or the user.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class EmbeddedResource extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -1025,15 +1117,14 @@ export class EmbeddedResource extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/
   annotations: /*#__PURE__*/optional(Annotations)
 })) {}
 /**
- * A resource that the server is capable of reading, included in a prompt or
- * tool call result.
+ * Represents a readable resource included in a prompt or tool call result.
  *
  * **Gotchas**
  *
  * Resource links returned by tools are not guaranteed to appear in the results
  * of `resources/list` requests.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class ResourceLink extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -1041,10 +1132,10 @@ export class ResourceLink extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sche
   type: /*#__PURE__*/Schema.tag("resource_link")
 })) {}
 /**
- * Union of MCP content blocks that can appear in prompt messages or tool
- * results, including text, media, embedded resources, and resource links.
+ * Schema for MCP content blocks that can appear in prompt messages or tool
+ * results.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export const ContentBlock = /*#__PURE__*/Schema.Union([TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink]);
@@ -1056,7 +1147,7 @@ export const ContentBlock = /*#__PURE__*/Schema.Union([TextContent, ImageContent
  * This is similar to `SamplingMessage`, but also supports the embedding of
  * resources from the MCP server.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class PromptMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.Struct({
@@ -1064,9 +1155,9 @@ export class PromptMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sch
   content: ContentBlock
 })) {}
 /**
- * The server's response to a prompts/list request from the client.
+ * Represents the server response to a prompts/list request from the client.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class ListPromptsResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/ListPromptsResult")({
@@ -1077,7 +1168,7 @@ export class ListPromptsResult extends /*#__PURE__*/Schema.Class("@effect/ai/Mcp
  * Sent from the client to request a list of prompts and prompt templates the
  * server has.
  *
- * @category prompts
+ * @category protocols
  * @since 4.0.0
  */
 export class ListPrompts extends /*#__PURE__*/Rpc.make("prompts/list", {
@@ -1086,9 +1177,9 @@ export class ListPrompts extends /*#__PURE__*/Rpc.make("prompts/list", {
   payload: /*#__PURE__*/Schema.UndefinedOr(PaginatedRequestMeta)
 }) {}
 /**
- * The server's response to a prompts/get request from the client.
+ * Represents the server response to a prompts/get request from the client.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class GetPromptResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/GetPromptResult")({
@@ -1100,9 +1191,9 @@ export class GetPromptResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSc
   description: /*#__PURE__*/optional(Schema.String)
 }) {}
 /**
- * Used by the client to get a prompt provided by the server.
+ * Sent from the client to get a prompt provided by the server.
  *
- * @category prompts
+ * @category protocols
  * @since 4.0.0
  */
 export class GetPrompt extends /*#__PURE__*/Rpc.make("prompts/get", {
@@ -1122,11 +1213,17 @@ export class GetPrompt extends /*#__PURE__*/Rpc.make("prompts/get", {
   }
 }) {}
 /**
- * An optional notification from the server to the client, informing it that
- * the list of prompts it offers has changed. This may be issued by servers
- * without any previous subscription from the client.
+ * Represents a notification that the server's prompt list changed.
  *
- * @category prompts
+ * **When to use**
+ *
+ * Use to notify clients that `prompts/list` should be requested again.
+ *
+ * **Details**
+ *
+ * Servers may send this notification without a previous client subscription.
+ *
+ * @category protocols
  * @since 4.0.0
  */
 export class PromptListChangedNotification extends /*#__PURE__*/Rpc.make("notifications/prompts/list_changed", {
@@ -1136,7 +1233,7 @@ export class PromptListChangedNotification extends /*#__PURE__*/Rpc.make("notifi
 // Tools
 // =============================================================================
 /**
- * Additional properties describing a Tool to clients.
+ * Schema for additional properties describing a tool to clients.
  *
  * **Details**
  *
@@ -1192,7 +1289,7 @@ export class ToolAnnotations extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
   openWorldHint: /*#__PURE__*/optionalWithDefault(Schema.Boolean, constTrue)
 })) {}
 /**
- * Definition for a tool the client can call.
+ * Schema for the definition of a tool the client can call.
  *
  * @category tools
  * @since 4.0.0
@@ -1226,7 +1323,7 @@ export class Tool extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Tool")
   _meta: /*#__PURE__*/optional(/*#__PURE__*/Schema.Record(Schema.String, Schema.Json))
 }) {}
 /**
- * The server's response to a tools/list request from the client.
+ * Schema for the server's response to a tools/list request from the client.
  *
  * @category tools
  * @since 4.0.0
@@ -1247,7 +1344,7 @@ export class ListTools extends /*#__PURE__*/Rpc.make("tools/list", {
   payload: /*#__PURE__*/Schema.UndefinedOr(PaginatedRequestMeta)
 }) {}
 /**
- * The server's response to a tool call.
+ * Schema for the server's response to a tool call.
  *
  * **Details**
  *
@@ -1273,7 +1370,15 @@ export class CallToolResult extends /*#__PURE__*/Schema.Class("@effect/ai/McpSch
   isError: /*#__PURE__*/optional(Schema.Boolean)
 }) {}
 /**
- * Used by the client to invoke a tool provided by the server.
+ * Represents a client request to invoke a tool provided by the server.
+ *
+ * **When to use**
+ *
+ * Use when a client already knows the tool name and wants the server to execute
+ * it with argument values.
+ *
+ * @see {@link ListTools} for discovering available tools before calling one
+ * @see {@link CallToolResult} for the successful tool-call result shape
  *
  * @category tools
  * @since 4.0.0
@@ -1288,9 +1393,15 @@ export class CallTool extends /*#__PURE__*/Rpc.make("tools/call", {
   }
 }) {}
 /**
- * An optional notification from the server to the client, informing it that
- * the list of tools it offers has changed. This may be issued by servers
- * without any previous subscription from the client.
+ * Represents a notification that the server's tool list changed.
+ *
+ * **When to use**
+ *
+ * Use to notify clients that `tools/list` should be requested again.
+ *
+ * **Details**
+ *
+ * Servers may send this notification without a previous client subscription.
  *
  * @category tools
  * @since 4.0.0
@@ -1302,8 +1413,8 @@ export class ToolListChangedNotification extends /*#__PURE__*/Rpc.make("notifica
 // Logging
 // =============================================================================
 /**
- * The severity of a log message, mapped to syslog message severities as
- * specified in RFC 5424 section 6.2.1:
+ * Schema for log message severity levels, mapped to syslog message severities
+ * as specified in RFC 5424 section 6.2.1:
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1.
  *
  * @category logging
@@ -1311,7 +1422,7 @@ export class ToolListChangedNotification extends /*#__PURE__*/Rpc.make("notifica
  */
 export const LoggingLevel = /*#__PURE__*/Schema.Literals(["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]);
 /**
- * A request from the client to the server, to enable or adjust logging.
+ * Sent from the client to the server to enable or adjust logging.
  *
  * @category logging
  * @since 4.0.0
@@ -1329,7 +1440,7 @@ export class SetLevel extends /*#__PURE__*/Rpc.make("logging/setLevel", {
   error: McpError
 }) {}
 /**
- * Server notification carrying a log message for the client.
+ * Sent from the server to the client carrying a log message.
  *
  * **Details**
  *
@@ -1371,7 +1482,7 @@ export class SamplingMessage extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
   content: /*#__PURE__*/Schema.Union([TextContent, ImageContent, AudioContent])
 })) {}
 /**
- * Hints to use for model selection.
+ * Schema for model selection hints.
  *
  * **Details**
  *
@@ -1397,8 +1508,8 @@ export class ModelHint extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Schema.
   name: /*#__PURE__*/optional(Schema.String)
 })) {}
 /**
- * The server's preferences for model selection, requested of the client during
- * sampling.
+ * Schema for the server's model selection preferences requested of the client
+ * during sampling.
  *
  * **Details**
  *
@@ -1457,10 +1568,16 @@ export class ModelPreferences extends /*#__PURE__*/Schema.Class("@effect/ai/McpS
   })))
 }) {}
 /**
- * The client's response to a sampling/create_message request from the server.
- * The client should inform the user before returning the sampled message, to
- * allow them to inspect the response (human in the loop) and decide whether to
- * allow the server to see it.
+ * Represents a client response to an MCP sampling request.
+ *
+ * **When to use**
+ *
+ * Use to return the message produced by client-side model sampling.
+ *
+ * **Details**
+ *
+ * The client should let the user inspect the sampled message before returning
+ * it to the server.
  *
  * @category sampling
  * @since 4.0.0
@@ -1476,10 +1593,17 @@ export class CreateMessageResult extends /*#__PURE__*/Schema.Class("@effect/ai/M
   stopReason: /*#__PURE__*/optional(Schema.String)
 }) {}
 /**
- * A request from the server to sample an LLM via the client. The client has
- * full discretion over which model to select. The client should also inform the
- * user before beginning sampling, to allow them to inspect the request (human
- * in the loop) and decide whether to approve it.
+ * Represents a server request for the client to sample an LLM.
+ *
+ * **When to use**
+ *
+ * Use when an MCP server needs the client to perform model sampling on its
+ * behalf.
+ *
+ * **Details**
+ *
+ * The client chooses the model and should ask the user to approve the sampling
+ * request before it begins.
  *
  * @category sampling
  * @since 4.0.0
@@ -1522,7 +1646,7 @@ export class CreateMessage extends /*#__PURE__*/Rpc.make("sampling/createMessage
 // Autocomplete
 // =============================================================================
 /**
- * A reference to a resource or resource template definition.
+ * Schema for a reference to a resource or resource template definition.
  *
  * @category autocomplete
  * @since 4.0.0
@@ -1535,7 +1659,7 @@ export class ResourceReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*
   uri: Schema.String
 })) {}
 /**
- * Identifies a prompt.
+ * Schema for a prompt reference used in autocomplete requests.
  *
  * @category autocomplete
  * @since 4.0.0
@@ -1549,7 +1673,7 @@ export class PromptReference extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/S
   title: /*#__PURE__*/optional(Schema.String)
 })) {}
 /**
- * The server's response to a completion/complete request
+ * Schema for the server's response to a completion/complete request.
  *
  * @category autocomplete
  * @since 4.0.0
@@ -1586,7 +1710,7 @@ export class CompleteResult extends /*#__PURE__*/Schema.Opaque()(/*#__PURE__*/Sc
   });
 }
 /**
- * A request from the client to the server, to ask for completion options.
+ * Sent from the client to the server to ask for completion options.
  *
  * @category autocomplete
  * @since 4.0.0
@@ -1646,9 +1770,11 @@ export class Root extends /*#__PURE__*/Schema.Class("@effect/ai/McpSchema/Root")
   name: /*#__PURE__*/optional(Schema.String)
 }) {}
 /**
- * The client's response to a roots/list request from the server. This result
- * contains an array of Root objects, each representing a root directory or file
- * that the server can operate on.
+ * Represents a client response containing the roots available to the server.
+ *
+ * **When to use**
+ *
+ * Use to return the directories or files that an MCP server may operate on.
  *
  * @category roots
  * @since 4.0.0
@@ -1677,10 +1803,15 @@ export class ListRoots extends /*#__PURE__*/Rpc.make("roots/list", {
   payload: /*#__PURE__*/Schema.UndefinedOr(RequestMeta)
 }) {}
 /**
- * A notification from the client to the server, informing it that the list of
- * roots has changed. This notification should be sent whenever the client adds,
- * removes, or modifies any root. The server should then request an updated list
- * of roots using the ListRootsRequest.
+ * Represents a notification that the client's root list changed.
+ *
+ * **When to use**
+ *
+ * Use to tell the server that it should request an updated roots list.
+ *
+ * **Details**
+ *
+ * Send this when the client adds, removes, or modifies a root.
  *
  * @category roots
  * @since 4.0.0
@@ -1692,7 +1823,7 @@ export class RootsListChangedNotification extends /*#__PURE__*/Rpc.make("notific
 // Elicitation
 // =============================================================================
 /**
- * The client's response to an elicitation request
+ * Schema for an accepted client response to an elicitation request.
  *
  * @category elicitation
  * @since 4.0.0
@@ -1713,7 +1844,7 @@ export class ElicitAcceptResult extends /*#__PURE__*/Schema.Class("@effect/ai/Mc
   content: Schema.Any
 }) {}
 /**
- * The client's response to an elicitation request
+ * Schema for a declined or canceled client response to an elicitation request.
  *
  * @category elicitation
  * @since 4.0.0
@@ -1729,15 +1860,15 @@ export class ElicitDeclineResult extends /*#__PURE__*/Schema.Class("@effect/ai/M
   action: /*#__PURE__*/Schema.Literals(["cancel", "decline"])
 }) {}
 /**
- * The client's response to an elicitation request
+ * Schema for every client response to an elicitation request.
  *
  * @category elicitation
  * @since 4.0.0
  */
 export const ElicitResult = /*#__PURE__*/Schema.Union([ElicitAcceptResult, ElicitDeclineResult]);
 /**
- * Request sent by the server asking the client to collect structured input
- * from the user.
+ * Sent from the server asking the client to collect structured input from the
+ * user.
  *
  * **Details**
  *
@@ -1812,7 +1943,7 @@ export class McpServerClientMiddleware extends /*#__PURE__*/RpcMiddleware.Servic
  * completion, and ping requests, and installs `McpServerClientMiddleware` for
  * handlers.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ClientRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, Initialize, Complete, SetLevel, GetPrompt, ListPrompts, ListResources, ListResourceTemplates, ReadResource, Subscribe, Unsubscribe, CallTool, ListTools).middleware(McpServerClientMiddleware) {}
@@ -1820,14 +1951,14 @@ export class ClientRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, Initiali
  * RPC group for notifications that MCP clients send to the server, such as
  * cancellation, progress, initialization completion, and roots list changes.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ClientNotificationRpcs extends /*#__PURE__*/RpcGroup.make(CancelledNotification, ProgressNotification, InitializedNotification, RootsListChangedNotification) {}
 /**
  * RPC group combining all client-to-server MCP requests and notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ClientRpcs extends /*#__PURE__*/ClientRequestRpcs.merge(ClientNotificationRpcs) {}
@@ -1835,7 +1966,7 @@ export class ClientRpcs extends /*#__PURE__*/ClientRequestRpcs.merge(ClientNotif
  * RPC group for requests that an MCP server can send to a client, including
  * ping, sampling, roots listing, and elicitation.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ServerRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, CreateMessage, ListRoots, Elicit) {}
@@ -1844,7 +1975,7 @@ export class ServerRequestRpcs extends /*#__PURE__*/RpcGroup.make(Ping, CreateMe
  * including cancellation, progress, logging, and list or resource update
  * notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ServerNotificationRpcs extends /*#__PURE__*/RpcGroup.make(CancelledNotification, ProgressNotification, LoggingMessageNotification, ResourceUpdatedNotification, ResourceListChangedNotification, ToolListChangedNotification, PromptListChangedNotification) {}
@@ -1860,7 +1991,7 @@ export function isParam(schema) {
   return Predicate.hasProperty(schema, ParamSchemaTypeId);
 }
 /**
- * Helper to create a param for a resource URI template.
+ * Creates a parameter for a resource URI template.
  *
  * @category parameters
  * @since 4.0.0