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

package/src/unstable/ai/McpSchema.ts

@@ -110,9 +110,9 @@ export const optional = <S extends Schema.Top>(schema: S): Schema.decodeTo<Schem
 // =============================================================================
 
 /**
- * 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: Schema.Union<[
@@ -121,18 +121,18 @@ export const RequestId: Schema.Union<[
 ]> = Schema.Union([Schema.String, Schema.Number])
 
 /**
- * A uniquely identifying ID for a request in JSON-RPC.
+ * Type represented by the JSON-RPC request identifier schema.
  *
- * @category common
+ * @category models
  * @since 4.0.0
  */
 export type RequestId = typeof RequestId.Type
 
 /**
- * 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: Schema.Union<[
@@ -141,10 +141,9 @@ export const ProgressToken: Schema.Union<[
 ]> = Schema.Union([Schema.String, Schema.Number])
 
 /**
- * A progress token, used to associate progress notifications with the original
- * request.
+ * Type represented by the MCP progress token schema.
  *
- * @category common
+ * @category models
  * @since 4.0.0
  */
 export type ProgressToken = typeof ProgressToken.Type
@@ -157,7 +156,7 @@ export type ProgressToken = typeof ProgressToken.Type
  * 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 Schema.Opaque<RequestMeta>()(Schema.Struct({
@@ -181,7 +180,7 @@ export class RequestMeta extends Schema.Opaque<RequestMeta>()(Schema.Struct({
  * 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 Schema.Opaque<ResultMeta>()(Schema.Struct({
@@ -200,7 +199,7 @@ export class ResultMeta extends Schema.Opaque<ResultMeta>()(Schema.Struct({
  * 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 Schema.Opaque<NotificationMeta>()(Schema.Struct({
@@ -212,9 +211,9 @@ export class NotificationMeta extends Schema.Opaque<NotificationMeta>()(Schema.S
 })) {}
 
 /**
- * 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: typeof Schema.String = Schema.String
@@ -226,7 +225,7 @@ export const Cursor: typeof Schema.String = Schema.String
  *
  * A cursor is an opaque string token used to continue paginated requests.
  *
- * @category common
+ * @category models
  * @since 4.0.0
  */
 export type Cursor = typeof Cursor.Type
@@ -239,7 +238,7 @@ export type Cursor = typeof Cursor.Type
  * 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 Schema.Opaque<PaginatedRequestMeta>()(Schema.Struct({
@@ -259,7 +258,7 @@ export class PaginatedRequestMeta extends Schema.Opaque<PaginatedRequestMeta>()(
  * 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 Schema.Opaque<PaginatedResultMeta>()(Schema.Struct({
@@ -272,9 +271,9 @@ export class PaginatedResultMeta extends Schema.Opaque<PaginatedResultMeta>()(Sc
 })) {}
 
 /**
- * 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: Schema.Literals<["user", "assistant"]> = Schema.Literals(["user", "assistant"])
@@ -286,16 +285,20 @@ export const Role: Schema.Literals<["user", "assistant"]> = Schema.Literals(["us
  *
  * Valid roles are `"user"` and `"assistant"`.
  *
- * @category common
+ * @category models
  * @since 4.0.0
  */
 export type Role = typeof Role.Type
 
 /**
- * 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**
  *
- * @category common
+ * Use to describe intended audience and priority metadata for objects shown or
+ * processed by a client.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export class Annotations extends Schema.Opaque<Annotations>()(Schema.Struct({
@@ -319,7 +322,7 @@ export class Annotations extends Schema.Opaque<Annotations>()(Schema.Struct({
 /**
  * Describes the name and version of an MCP implementation.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class Implementation extends Schema.Opaque<Implementation>()(Schema.Struct({
@@ -329,11 +332,19 @@ export class Implementation extends Schema.Opaque<Implementation>()(Schema.Struc
 })) {}
 
 /**
- * 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.
+ *
+ * **Details**
+ *
+ * Known capabilities are represented by this schema, but the capability set is
+ * open and clients may define additional capabilities.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class ClientCapabilities extends Schema.Class<ClientCapabilities>(
@@ -368,11 +379,19 @@ export class ClientCapabilities extends Schema.Class<ClientCapabilities>(
 }) {}
 
 /**
- * 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**
+ *
+ * Known capabilities are represented by this schema, but the capability set is
+ * open and servers may define additional capabilities.
  *
- * @category common
+ * @category schemas
  * @since 4.0.0
  */
 export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Schema.Struct({
@@ -431,14 +450,14 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
 // =============================================================================
 
 /**
- * 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 Schema.Class<McpErrorBase>(
@@ -461,45 +480,76 @@ export class McpErrorBase extends Schema.Class<McpErrorBase>(
 }) {}
 
 /**
- * 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 as const
 /**
- * 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 as const
 /**
- * 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 as const
 /**
- * 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 as const
 /**
- * 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 as const
 
 /**
- * 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
@@ -511,8 +561,16 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
 }) {}
 
 /**
- * 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
@@ -524,8 +582,15 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
 }) {}
 
 /**
- * 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
@@ -537,8 +602,16 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
 }) {}
 
 /**
- * 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
@@ -550,8 +623,16 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
 }) {}
 
 /**
- * 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
@@ -586,9 +667,15 @@ export const McpError = Schema.Union([
 // =============================================================================
 
 /**
- * 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
@@ -604,8 +691,7 @@ export class Ping extends Rpc.make("ping", {
 // =============================================================================
 
 /**
- * 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
@@ -631,8 +717,8 @@ export class InitializeResult extends Schema.Opaque<InitializeResult>()(Schema.S
 })) {}
 
 /**
- * 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
@@ -661,8 +747,7 @@ export class Initialize extends 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
@@ -676,8 +761,8 @@ export class InitializedNotification extends Rpc.make("notifications/initialized
 // =============================================================================
 
 /**
- * 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**
  *
@@ -710,8 +795,7 @@ export class CancelledNotification extends Rpc.make("notifications/cancelled", {
 // =============================================================================
 
 /**
- * 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
@@ -745,7 +829,7 @@ export class ProgressNotification extends Rpc.make("notifications/progress", {
 // =============================================================================
 
 /**
- * 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
@@ -797,7 +881,7 @@ export class Resource extends Schema.Class<Resource>(
 }) {}
 
 /**
- * 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
@@ -843,7 +927,7 @@ export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
 }) {}
 
 /**
- * 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
@@ -864,7 +948,7 @@ export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.S
 })) {}
 
 /**
- * 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
@@ -879,7 +963,7 @@ export class TextResourceContents extends Schema.Opaque<TextResourceContents>()(
 })) {}
 
 /**
- * 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
@@ -893,7 +977,7 @@ export class BlobResourceContents extends Schema.Opaque<BlobResourceContents>()(
 })) {}
 
 /**
- * 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
@@ -918,7 +1002,8 @@ export class ListResources extends Rpc.make("resources/list", {
 }) {}
 
 /**
- * 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
@@ -943,7 +1028,7 @@ export class ListResourceTemplates extends Rpc.make("resources/templates/list",
 }) {}
 
 /**
- * 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
@@ -973,9 +1058,15 @@ export class ReadResource extends 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
@@ -1024,7 +1115,7 @@ export class Unsubscribe extends 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**
  *
@@ -1051,7 +1142,7 @@ export class ResourceUpdatedNotification extends Rpc.make("notifications/resourc
 /**
  * Describes an argument that a prompt can accept.
  *
- * @category prompts
+ * @category schemas
  * @since 4.0.0
  */
 export class PromptArgument extends Schema.Opaque<PromptArgument>()(Schema.Struct({
@@ -1071,9 +1162,9 @@ export class PromptArgument extends Schema.Opaque<PromptArgument>()(Schema.Struc
 })) {}
 
 /**
- * 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 Schema.Class<Prompt>(
@@ -1095,9 +1186,9 @@ export class Prompt extends Schema.Class<Prompt>(
 }) {}
 
 /**
- * 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 Schema.Opaque<TextContent>()(Schema.Struct({
@@ -1113,9 +1204,9 @@ export class TextContent extends Schema.Opaque<TextContent>()(Schema.Struct({
 })) {}
 
 /**
- * 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 Schema.Opaque<ImageContent>()(Schema.Struct({
@@ -1136,9 +1227,9 @@ export class ImageContent extends Schema.Opaque<ImageContent>()(Schema.Struct({
 })) {}
 
 /**
- * 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 Schema.Opaque<AudioContent>()(Schema.Struct({
@@ -1159,14 +1250,14 @@ export class AudioContent extends Schema.Opaque<AudioContent>()(Schema.Struct({
 })) {}
 
 /**
- * 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 Schema.Opaque<EmbeddedResource>()(Schema.Struct({
@@ -1179,15 +1270,14 @@ export class EmbeddedResource extends Schema.Opaque<EmbeddedResource>()(Schema.S
 })) {}
 
 /**
- * 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 Schema.Opaque<ResourceLink>()(Schema.Struct({
@@ -1196,10 +1286,10 @@ export class ResourceLink extends Schema.Opaque<ResourceLink>()(Schema.Struct({
 })) {}
 
 /**
- * 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 = Schema.Union([
@@ -1218,7 +1308,7 @@ export const ContentBlock = Schema.Union([
  * 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 Schema.Opaque<PromptMessage>()(Schema.Struct({
@@ -1227,9 +1317,9 @@ export class PromptMessage extends Schema.Opaque<PromptMessage>()(Schema.Struct(
 })) {}
 
 /**
- * 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 Schema.Class<ListPromptsResult>(
@@ -1243,7 +1333,7 @@ export class ListPromptsResult extends Schema.Class<ListPromptsResult>(
  * 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 Rpc.make("prompts/list", {
@@ -1253,9 +1343,9 @@ export class ListPrompts extends Rpc.make("prompts/list", {
 }) {}
 
 /**
- * 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 Schema.Class<GetPromptResult>(
@@ -1270,9 +1360,9 @@ export class GetPromptResult extends Schema.Class<GetPromptResult>(
 }) {}
 
 /**
- * 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 Rpc.make("prompts/get", {
@@ -1293,11 +1383,17 @@ export class GetPrompt extends 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.
+ *
+ * **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 prompts
+ * @category protocols
  * @since 4.0.0
  */
 export class PromptListChangedNotification extends Rpc.make("notifications/prompts/list_changed", {
@@ -1309,7 +1405,7 @@ export class PromptListChangedNotification extends Rpc.make("notifications/promp
 // =============================================================================
 
 /**
- * Additional properties describing a Tool to clients.
+ * Schema for additional properties describing a tool to clients.
  *
  * **Details**
  *
@@ -1366,7 +1462,7 @@ export class ToolAnnotations extends Schema.Opaque<ToolAnnotations>()(Schema.Str
 })) {}
 
 /**
- * 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
@@ -1403,7 +1499,7 @@ export class Tool extends Schema.Class<Tool>(
 }) {}
 
 /**
- * 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
@@ -1428,7 +1524,7 @@ export class ListTools extends Rpc.make("tools/list", {
 }) {}
 
 /**
- * The server's response to a tool call.
+ * Schema for the server's response to a tool call.
  *
  * **Details**
  *
@@ -1455,7 +1551,15 @@ export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/Mcp
 }) {}
 
 /**
- * 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
@@ -1474,9 +1578,15 @@ export class CallTool extends 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
@@ -1490,8 +1600,8 @@ export class ToolListChangedNotification extends Rpc.make("notifications/tools/l
 // =============================================================================
 
 /**
- * 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
@@ -1528,7 +1638,7 @@ export const LoggingLevel: Schema.Literals<[
 export type LoggingLevel = typeof LoggingLevel.Type
 
 /**
- * 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
@@ -1547,7 +1657,7 @@ export class SetLevel extends Rpc.make("logging/setLevel", {
 }) {}
 
 /**
- * Server notification carrying a log message for the client.
+ * Sent from the server to the client carrying a log message.
  *
  * **Details**
  *
@@ -1592,7 +1702,7 @@ export class SamplingMessage extends Schema.Opaque<SamplingMessage>()(Schema.Str
 })) {}
 
 /**
- * Hints to use for model selection.
+ * Schema for model selection hints.
  *
  * **Details**
  *
@@ -1619,8 +1729,8 @@ export class ModelHint extends Schema.Opaque<ModelHint>()(Schema.Struct({
 })) {}
 
 /**
- * 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**
  *
@@ -1673,10 +1783,16 @@ export class ModelPreferences extends Schema.Class<ModelPreferences>(
 }) {}
 
 /**
- * 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
@@ -1695,10 +1811,17 @@ export class CreateMessageResult extends Schema.Class<CreateMessageResult>(
 }) {}
 
 /**
- * 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
@@ -1743,7 +1866,7 @@ export class CreateMessage extends Rpc.make("sampling/createMessage", {
 // =============================================================================
 
 /**
- * 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
@@ -1757,7 +1880,7 @@ export class ResourceReference extends Schema.Opaque<ResourceReference>()(Schema
 })) {}
 
 /**
- * Identifies a prompt.
+ * Schema for a prompt reference used in autocomplete requests.
  *
  * @category autocomplete
  * @since 4.0.0
@@ -1772,7 +1895,7 @@ export class PromptReference extends Schema.Opaque<PromptReference>()(Schema.Str
 })) {}
 
 /**
- * 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
@@ -1810,7 +1933,7 @@ export class CompleteResult extends Schema.Opaque<CompleteResult>()(Schema.Struc
 }
 
 /**
- * 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
@@ -1879,9 +2002,11 @@ export class Root extends Schema.Class<Root>(
 }) {}
 
 /**
- * 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
@@ -1914,10 +2039,15 @@ export class ListRoots extends Rpc.make("roots/list", {
 }) {}
 
 /**
- * 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
@@ -1931,7 +2061,7 @@ export class RootsListChangedNotification extends Rpc.make("notifications/roots/
 // =============================================================================
 
 /**
- * The client's response to an elicitation request
+ * Schema for an accepted client response to an elicitation request.
  *
  * @category elicitation
  * @since 4.0.0
@@ -1955,7 +2085,7 @@ export class ElicitAcceptResult extends Schema.Class<ElicitAcceptResult>(
 }) {}
 
 /**
- * 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
@@ -1974,7 +2104,7 @@ export class ElicitDeclineResult extends Schema.Class<ElicitDeclineResult>(
 }) {}
 
 /**
- * The client's response to an elicitation request
+ * Schema for every client response to an elicitation request.
  *
  * @category elicitation
  * @since 4.0.0
@@ -1985,8 +2115,8 @@ export const ElicitResult = Schema.Union([
 ])
 
 /**
- * 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**
  *
@@ -2077,7 +2207,7 @@ export class McpServerClientMiddleware extends RpcMiddleware.Service<McpServerCl
  * Encoded JSON-RPC request message for an RPC in `Group`, including the request
  * id, method, and encoded payload.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type RequestEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
@@ -2101,7 +2231,7 @@ export type RequestEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
  * Encoded notification message for an RPC in `Group`, including the method and
  * encoded payload without a request id.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type NotificationEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
@@ -2124,7 +2254,7 @@ export type NotificationEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
  * Encoded success response for an RPC in `Group`, containing the original
  * request id and encoded result.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type SuccessEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
@@ -2147,7 +2277,7 @@ export type SuccessEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
  * Encoded failure response for an RPC in `Group`, containing the original
  * request id and encoded error.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type FailureEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
@@ -2175,7 +2305,7 @@ export type FailureEncoded<Group extends RpcGroup.Any> = RpcGroup.Rpcs<
  * completion, and ping requests, and installs `McpServerClientMiddleware` for
  * handlers.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ClientRequestRpcs extends RpcGroup.make(
@@ -2197,7 +2327,7 @@ export class ClientRequestRpcs extends RpcGroup.make(
 /**
  * Encoded union of all client-to-server MCP request messages.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>
@@ -2206,7 +2336,7 @@ export type ClientRequestEncoded = RequestEncoded<typeof ClientRequestRpcs>
  * 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 RpcGroup.make(
@@ -2219,7 +2349,7 @@ export class ClientNotificationRpcs extends RpcGroup.make(
 /**
  * Encoded union of all client-to-server MCP notification messages.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotificationRpcs>
@@ -2227,7 +2357,7 @@ export type ClientNotificationEncoded = NotificationEncoded<typeof ClientNotific
 /**
  * RPC group combining all client-to-server MCP requests and notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ClientRpcs extends ClientRequestRpcs.merge(ClientNotificationRpcs) {}
@@ -2235,7 +2365,7 @@ export class ClientRpcs extends ClientRequestRpcs.merge(ClientNotificationRpcs)
 /**
  * Encoded success response sent by a client for a server-initiated request.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>
@@ -2243,7 +2373,7 @@ export type ClientSuccessEncoded = SuccessEncoded<typeof ServerRequestRpcs>
 /**
  * Encoded failure response sent by a client for a server-initiated request.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>
@@ -2252,7 +2382,7 @@ export type ClientFailureEncoded = FailureEncoded<typeof ServerRequestRpcs>
  * 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 RpcGroup.make(
@@ -2265,7 +2395,7 @@ export class ServerRequestRpcs extends RpcGroup.make(
 /**
  * Encoded union of all server-to-client MCP request messages.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>
@@ -2275,7 +2405,7 @@ export type ServerRequestEncoded = RequestEncoded<typeof ServerRequestRpcs>
  * including cancellation, progress, logging, and list or resource update
  * notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ServerNotificationRpcs extends RpcGroup.make(
@@ -2291,7 +2421,7 @@ export class ServerNotificationRpcs extends RpcGroup.make(
 /**
  * Encoded union of all server-to-client MCP notification messages.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotificationRpcs>
@@ -2299,7 +2429,7 @@ export type ServerNotificationEncoded = NotificationEncoded<typeof ServerNotific
 /**
  * Encoded success response sent by the server for a client-initiated request.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>
@@ -2307,7 +2437,7 @@ export type ServerSuccessEncoded = SuccessEncoded<typeof ClientRequestRpcs>
 /**
  * Encoded failure response sent by the server for a client-initiated request.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>
@@ -2315,7 +2445,7 @@ export type ServerFailureEncoded = FailureEncoded<typeof ClientRequestRpcs>
 /**
  * Encoded server response to a client request, either success or failure.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded
@@ -2324,7 +2454,7 @@ export type ServerResultEncoded = ServerSuccessEncoded | ServerFailureEncoded
  * Encoded MCP messages accepted from a client by the server protocol: client
  * requests and client notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded
@@ -2333,7 +2463,7 @@ export type FromClientEncoded = ClientRequestEncoded | ClientNotificationEncoded
  * Encoded MCP messages emitted by the server protocol to a client: server
  * responses and server notifications.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export type FromServerEncoded = ServerResultEncoded | ServerNotificationEncoded
@@ -2388,7 +2518,7 @@ export interface Param<Name extends string, S extends Schema.Top> extends
 }
 
 /**
- * Helper to create a param for a resource URI template.
+ * Creates a parameter for a resource URI template.
  *
  * @category parameters
  * @since 4.0.0