effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -41,39 +41,36 @@ import * as JsonSchema from "../../JsonSchema.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import * as LanguageModel from "./LanguageModel.ts"
 import * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
 import * as Tool from "./Tool.ts"
 
 /**
- * Transforms a `Schema.Codec` into a form compatible with Anthropic's structured output constraints.
+ * Converts a `Schema.Codec` to Anthropic structured-output JSON Schema and a
+ * matching codec for model output.
  *
  * **When to use**
  *
- * Use to adapt an `Effect` `Schema.Codec` for Anthropic structured output by
- * returning an Anthropic-compatible JSON Schema together with a codec that
- * preserves the decoded value type.
+ * Use when you send Effect Schema-backed structured output requests to
+ * Anthropic and need provider-compatible JSON Schema without losing the decoded
+ * application type.
  *
  * **Details**
  *
- * The transformation walks the schema AST and rewrites constructs that Anthropic does not support natively:
+ * Returns the JSON Schema to include in the request and the codec to use when
+ * decoding the model response. If the input schema already fits Anthropic's
+ * supported JSON Schema subset, the original codec is returned unchanged.
  *
- * - **Tuples** are converted to objects with numeric string keys (e.g.
- *   `"0"`, `"1"`) since Anthropic does not support tuple schemas. Rest
- *   elements are placed under a `"__rest__"` key.
- * - **Optional properties** are replaced with `T | null` unions, because
- *   Anthropic requires all properties to be present.
- * - **Records** (index signatures) are converted to arrays of `[key, value]`
- *   pairs.
- * - **`oneOf` unions** are rewritten as `anyOf` unions.
- * - **Filters and annotations** are preserved where compatible (e.g.
- *   `description`, supported `format` values like `"date-time"`, `"email"`,
- *   `"uuid"`, etc.), and stripped otherwise.
+ * **Gotchas**
  *
- * If the schema is already compatible, the original codec is returned
- * unchanged.
+ * - Some schemas use a provider-safe encoded shape: tuples become objects with
+ *   numeric string keys, records become arrays of `[key, value]` pairs, and
+ *   optional properties become required nullable properties.
+ * - `oneOf` unions are emitted as `anyOf` unions.
+ * - Unsupported schema kinds throw during conversion instead of producing a
+ *   lossy schema.
  *
  * @see {@link LanguageModel.CodecTransformer} for the structured-output transformer contract
  * @see {@link OpenAiStructuredOutput.toCodecOpenAI} for the OpenAI-specific transformer
@@ -88,8 +85,10 @@ export function toCodecAnthropic<T, E, RD, RE>(
   readonly jsonSchema: JsonSchema.JsonSchema
 } {
   const to = schema.ast
-  const from = recur(AST.toEncoded(to))
-  const codec = from === to ? schema : Schema.make<typeof schema>(AST.decodeTo(from, to, Transformation.passthrough()))
+  const from = recur(SchemaAST.toEncoded(to))
+  const codec = from === to
+    ? schema
+    : Schema.make<typeof schema>(SchemaAST.decodeTo(from, to, SchemaTransformation.passthrough()))
   const document = JsonSchema.resolveTopLevel$ref(Schema.toJsonSchemaDocument(codec))
   const jsonSchema = { ...document.schema }
   if (Object.keys(document.definitions).length > 0) {
@@ -98,7 +97,7 @@ export function toCodecAnthropic<T, E, RD, RE>(
   return { codec, jsonSchema }
 }
 
-function recur(ast: AST.AST): AST.AST {
+function recur(ast: SchemaAST.AST): SchemaAST.AST {
   switch (ast._tag) {
     case "Declaration":
     case "Void":
@@ -126,14 +125,14 @@ function recur(ast: AST.AST): AST.AST {
     case "String": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.String(annotations, filters)
+        return new SchemaAST.String(annotations, filters)
       }
       return ast
     }
     case "Number": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.Number(annotations, filters)
+        return new SchemaAST.Number(annotations, filters)
       }
       return ast
     }
@@ -144,7 +143,7 @@ function recur(ast: AST.AST): AST.AST {
       if (typeof literal === "string" || typeof literal === "number" || typeof literal === "boolean") {
         const { annotations, filters } = get(ast)
         if (annotations !== undefined || filters !== undefined) {
-          return new AST.Literal(ast.literal, annotations, filters)
+          return new SchemaAST.Literal(ast.literal, annotations, filters)
         }
         return ast
       }
@@ -156,12 +155,12 @@ function recur(ast: AST.AST): AST.AST {
     }
     case "Union": {
       if (ast.mode === "oneOf") {
-        return new AST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
+        return new SchemaAST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
       }
-      const types = AST.mapOrSame(ast.types, recur)
+      const types = SchemaAST.mapOrSame(ast.types, recur)
       const { annotations, filters } = get(ast)
       if (types !== ast.types || annotations !== undefined || filters !== undefined) {
-        return new AST.Union(types, "anyOf", annotations, filters)
+        return new SchemaAST.Union(types, "anyOf", annotations, filters)
       }
       return ast
     }
@@ -181,15 +180,17 @@ function recur(ast: AST.AST): AST.AST {
           annotations.description = TUPLE_DESCRIPTION
         }
         const propertySignatures = ast.elements.map((e, i) => {
-          return new AST.PropertySignature(String(i), e)
+          return new SchemaAST.PropertySignature(String(i), e)
         })
         if (ast.rest.length === 1) {
-          propertySignatures.push(new AST.PropertySignature(REST_PROPERTY_NAME, new AST.Arrays(false, [], ast.rest)))
+          propertySignatures.push(
+            new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], ast.rest))
+          )
         }
-        return AST.decodeTo(
-          recur(new AST.Objects(propertySignatures, [], annotations, filters)),
+        return SchemaAST.decodeTo(
+          recur(new SchemaAST.Objects(propertySignatures, [], annotations, filters)),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: (o) => {
               let t: Array<unknown> = []
               for (let i = 0; i < ast.elements.length; i++) {
@@ -218,9 +219,9 @@ function recur(ast: AST.AST): AST.AST {
           })
         )
       } else {
-        const rest = AST.mapOrSame(ast.rest, recur)
+        const rest = SchemaAST.mapOrSame(ast.rest, recur)
         if (rest !== ast.rest || annotations !== undefined || filters !== undefined) {
-          return new AST.Arrays(false, [], rest, annotations, filters)
+          return new SchemaAST.Arrays(false, [], rest, annotations, filters)
         }
         return ast
       }
@@ -228,7 +229,7 @@ function recur(ast: AST.AST): AST.AST {
     case "Objects": {
       let { annotations, filters } = get(ast)
       if (ast.indexSignatures.length === 0) {
-        const propertySignatures = AST.mapOrSame(ast.propertySignatures, (ps) => {
+        const propertySignatures = SchemaAST.mapOrSame(ast.propertySignatures, (ps) => {
           if (typeof ps.name !== "string") {
             throw new Error(
               `${errorPrefix}: Property names must be strings (got ${typeof ps.name})`
@@ -236,11 +237,11 @@ function recur(ast: AST.AST): AST.AST {
           }
           let type = recur(ps.type)
           // opttional properties are not supported by Anthropic, so we translate them to nullable unions
-          if (AST.isOptional(ps.type)) {
-            type = AST.decodeTo(
-              new AST.Union([type, AST.null], "anyOf"),
-              AST.optionalKey(type),
-              Transformation.transformOptional({
+          if (SchemaAST.isOptional(ps.type)) {
+            type = SchemaAST.decodeTo(
+              new SchemaAST.Union([type, SchemaAST.null], "anyOf"),
+              SchemaAST.optionalKey(type),
+              SchemaTransformation.transformOptional({
                 decode: Option.filter(Predicate.isNotNull),
                 encode: Option.orElseSome(() => null)
               })
@@ -249,12 +250,12 @@ function recur(ast: AST.AST): AST.AST {
           if (type === ps.type) {
             return ps
           }
-          return new AST.PropertySignature(ps.name, type)
+          return new SchemaAST.PropertySignature(ps.name, type)
         })
         if (
           propertySignatures !== ast.propertySignatures || annotations !== undefined || filters !== undefined
         ) {
-          return new AST.Objects(propertySignatures, [], annotations, filters)
+          return new SchemaAST.Objects(propertySignatures, [], annotations, filters)
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
@@ -268,10 +269,12 @@ function recur(ast: AST.AST): AST.AST {
           annotations ??= {}
           annotations.description = RECORD_DESCRIPTION
         }
-        return AST.decodeTo(
-          recur(new AST.Arrays(false, [], [new AST.Arrays(false, [is.parameter, is.type], [])], annotations)),
+        return SchemaAST.decodeTo(
+          recur(
+            new SchemaAST.Arrays(false, [], [new SchemaAST.Arrays(false, [is.parameter, is.type], [])], annotations)
+          ),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: Object.fromEntries,
             encode: Object.entries
           })
@@ -288,7 +291,7 @@ function recur(ast: AST.AST): AST.AST {
 
 const errorPrefix = "AnthropicStructuredOutput"
 
-function unsupportedAst(ast: AST.AST, details?: string): never {
+function unsupportedAst(ast: SchemaAST.AST, details?: string): never {
   const base = `Unsupported AST ${ast._tag}`
   const full = `${errorPrefix}: ${base}`
   throw new Error(details !== undefined ? `${full} (${details})` : full)
@@ -308,14 +311,14 @@ type Annotation =
 
 type Filter =
   | Annotation
-  | { readonly _tag: "filter"; readonly filter: AST.Filter<any> }
+  | { readonly _tag: "filter"; readonly filter: SchemaAST.Filter<any> }
 
-const get = (ast: AST.AST): {
+const get = (ast: SchemaAST.AST): {
   annotations: Record<string, string> | undefined
-  filters: [AST.Check<any>, ...AST.Check<any>[]] | undefined
+  filters: [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]] | undefined
 } => {
   const annotations: Record<string, string> = {}
-  const filters: Array<AST.Filter<any>> = []
+  const filters: Array<SchemaAST.Filter<any>> = []
   const checks = getChecks(ast)
   if (checks.length > 0) {
     for (const check of checks) {
@@ -345,7 +348,7 @@ const get = (ast: AST.AST): {
   }
 }
 
-const getChecks = (ast: AST.AST): Array<Filter> => [
+const getChecks = (ast: SchemaAST.AST): Array<Filter> => [
   ...(ast.checks !== undefined ? getFilters(ast.checks) : []),
   ...getAnnotations(ast.annotations)
 ]
@@ -372,7 +375,7 @@ const getAnnotations = (annotations: Schema.Annotations.Filter | undefined): Arr
   return out
 }
 
-function getFilter(filter: AST.Filter<any>): Array<Filter> {
+function getFilter(filter: SchemaAST.Filter<any>): Array<Filter> {
   let out: Array<Filter> = []
   const annotations = getAnnotations(filter.annotations)
   const meta = filter.annotations?.meta
@@ -396,7 +399,7 @@ function getFilter(filter: AST.Filter<any>): Array<Filter> {
   return out
 }
 
-function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
+function resetFilter(filter: SchemaAST.Filter<any>): SchemaAST.Filter<any> {
   return filter.annotate({
     description: undefined,
     expected: undefined,
@@ -405,7 +408,7 @@ function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
   })
 }
 
-function getFilters(checks: readonly [AST.Check<any>, ...AST.Check<any>[]]): Array<Filter> {
+function getFilters(checks: readonly [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]]): Array<Filter> {
   return checks.flatMap((check) => {
     switch (check._tag) {
       case "Filter":

package/src/unstable/ai/Chat.ts

@@ -107,7 +107,7 @@ import type * as Tool from "./Tool.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class Chat extends Context.Service<Chat, Service>()(
@@ -505,8 +505,8 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  *
  * **When to use**
  *
- * Use when this is the most common way to start a fresh chat session without
- * any initial context or system prompts.
+ * Use when you need to start a fresh chat session without initial context or
+ * system prompts.
  *
  * **Example** (Creating an empty chat)
  *
@@ -725,7 +725,7 @@ export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
  * Use to provide the storage operations needed by persisted conversation
  * sessions.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 // @effect-diagnostics effect/leakingRequirements:off
@@ -797,9 +797,8 @@ export interface Persisted extends Service {
  *
  * **When to use**
  *
- * Use to construct the `Chat.Persistence` service from the current
- * `BackingPersistence` when you want to create and retrieve persisted chats
- * programmatically by chat id.
+ * Use when you need programmatic persisted chat creation and retrieval backed
+ * by the current `BackingPersistence`.
  *
  * **Details**
  *

package/src/unstable/ai/EmbeddingModel.ts

@@ -60,8 +60,8 @@ import * as AiError from "./AiError.ts"
  *
  * **When to use**
  *
- * Use to retrieve or provide an `EmbeddingModel.Service` when an `Effect`
- * program needs to embed text into vectors.
+ * Use to retrieve or provide the embedding model service for an `Effect`
+ * program that embeds text into vectors.
  *
  * @see {@link Service} for the service contract provided by this tag
  * @see {@link make} for constructing an embedding model service from a provider
@@ -146,7 +146,7 @@ export class EmbedManyResponse extends Schema.Class<EmbedManyResponse>(
 /**
  * Provider input options for embedding requests.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ProviderOptions {
@@ -171,8 +171,8 @@ export interface ProviderResponse {
  *
  * **When to use**
  *
- * Use when building or calling a low-level embedding request resolver and you
- * need a typed request for one input that resolves to `EmbedResponse`.
+ * Use when you need a typed request for one embedding input while building or
+ * calling a low-level embedding request resolver.
  *
  * @see {@link Service} for the resolver-bearing service contract
  * @see {@link make} for constructing the request resolver from a provider implementation

package/src/unstable/ai/IdGenerator.ts

@@ -81,7 +81,7 @@ import * as Random from "../../Random.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class IdGenerator extends Context.Service<IdGenerator, Service>()(
@@ -142,7 +142,7 @@ export interface Service {
  * // This will generate IDs like: "tool_A1B2C3D4"
  * ```
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface MakeOptions {
@@ -306,9 +306,8 @@ export const make = Effect.fnUntraced(function*({
  *
  * **When to use**
  *
- * Use when this is the recommended way to provide ID generation capabilities to your
- * application. The layer will fail during construction if the configuration is
- * invalid.
+ * Use when you need to provide ID generation capabilities from validated
+ * configuration.
  *
  * **Example** (Providing an ID generator layer)
  *

package/src/unstable/ai/LanguageModel.ts

@@ -61,7 +61,7 @@ import * as Predicate from "../../Predicate.ts"
 import * as Queue from "../../Queue.ts"
 import { CurrentConcurrency } from "../../References.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
 import * as Sink from "../../Sink.ts"
 import * as Stream from "../../Stream.ts"
 import type { Span } from "../../Tracer.ts"
@@ -104,7 +104,7 @@ import * as Toolkit from "./Toolkit.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class LanguageModel extends Context.Service<LanguageModel, Service>()(
@@ -261,7 +261,7 @@ export const defaultCodecTransformer: CodecTransformer = InternalCodecTransforme
 /**
  * Configuration options for text generation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
@@ -319,7 +319,7 @@ type GenerateTextOptionsWithoutToolkit = Omit<GenerateTextOptions<{}>, "toolkit"
 /**
  * Configuration options for structured object generation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface GenerateObjectOptions<
@@ -684,7 +684,7 @@ export type ExtractServices<Options> = Options extends {
  * underlying provider implementation, regardless of the specific provider being
  * used.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ProviderOptions {
@@ -758,8 +758,9 @@ export interface ProviderOptions {
  *
  * **When to use**
  *
- * Use to build a `LanguageModel.Service` from provider-specific final and
- * streaming text generation functions.
+ * Use when you are implementing a provider adapter and need to expose the
+ * standard language-model service while keeping provider-specific request hooks
+ * behind it.
  *
  * **Details**
  *
@@ -2209,7 +2210,7 @@ export const getObjectName = <StructuredOutputSchema extends Schema.Top>(
   if ("identifier" in schema && typeof schema.identifier === "string") {
     return schema.identifier
   }
-  const identifier = AST.resolveIdentifier(schema.ast)
+  const identifier = SchemaAST.resolveIdentifier(schema.ast)
   if (typeof identifier === "string") {
     return identifier
   }

package/src/unstable/ai/McpSchema.ts

@@ -35,7 +35,7 @@ import { constFalse, constTrue } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import * as Getter from "../../SchemaGetter.ts"
+import * as SchemaGetter from "../../SchemaGetter.ts"
 import type * as Scope from "../../Scope.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import type * as RpcClient from "../rpc/RpcClient.ts"
@@ -77,8 +77,8 @@ export const optionalWithDefault = <S extends Schema.Top & Schema.WithoutConstru
   const effect = Effect.sync(defaultValue)
   return Schema.optionalKey(schema).pipe(
     Schema.decode<Schema.optionalKey<S>>({
-      decode: Getter.withDefault(effect),
-      encode: Getter.passthrough()
+      decode: SchemaGetter.withDefault(effect),
+      encode: SchemaGetter.passthrough()
     }),
     Schema.withConstructorDefault<
       Schema.decodeTo<Schema.toType<Schema.optionalKey<S>>, Schema.optionalKey<S>>
@@ -100,8 +100,8 @@ export const optionalWithDefault = <S extends Schema.Top & Schema.WithoutConstru
 export const optional = <S extends Schema.Top>(schema: S): Schema.decodeTo<Schema.optional<S>, Schema.optionalKey<S>> =>
   Schema.optionalKey(schema).pipe(
     Schema.decodeTo(Schema.optional(schema), {
-      decode: Getter.passthrough() as any,
-      encode: Getter.transformOptional(Option.flatMap(Option.fromUndefinedOr))
+      decode: SchemaGetter.passthrough() as any,
+      encode: SchemaGetter.transformOptional(Option.flatMap(Option.fromUndefinedOr))
     })
   )
 
@@ -484,8 +484,8 @@ export class McpErrorBase extends Schema.Class<McpErrorBase>(
  *
  * **When to use**
  *
- * Use when you need the JSON-RPC error code for requests that are not valid
- * request objects.
+ * Use when building an MCP/JSON-RPC error response for a syntactically parsed
+ * request object that fails request-shape validation.
  *
  * @category constants
  * @since 4.0.0
@@ -497,8 +497,8 @@ export const INVALID_REQUEST_ERROR_CODE = -32600 as const
  *
  * **When to use**
  *
- * Use when you need the JSON-RPC error code for requests whose method does not
- * exist or is not available.
+ * Use when building an MCP/JSON-RPC error response for a request whose
+ * `method` is unknown or unavailable.
  *
  * @category constants
  * @since 4.0.0
@@ -509,7 +509,8 @@ export const METHOD_NOT_FOUND_ERROR_CODE = -32601 as const
  *
  * **When to use**
  *
- * Use when you need the JSON-RPC error code for invalid method parameters.
+ * Use when building an MCP/JSON-RPC error response for decoded request
+ * parameters that fail method-specific validation.
  *
  * @category constants
  * @since 4.0.0
@@ -520,7 +521,8 @@ export const INVALID_PARAMS_ERROR_CODE = -32602 as const
  *
  * **When to use**
  *
- * Use when you need the JSON-RPC error code for internal server errors.
+ * Use when building an MCP/JSON-RPC error response for an unexpected
+ * server-side failure.
  *
  * @category constants
  * @since 4.0.0
@@ -531,8 +533,8 @@ export const INTERNAL_ERROR_CODE = -32603 as const
  *
  * **When to use**
  *
- * Use when you need the JSON-RPC error code for invalid JSON that could not be
- * parsed.
+ * Use when building an MCP/JSON-RPC error response before a request object is
+ * available because the JSON payload could not be parsed.
  *
  * @category constants
  * @since 4.0.0
@@ -1555,8 +1557,8 @@ export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/Mcp
  *
  * **When to use**
  *
- * Use when a client already knows the tool name and wants the server to execute
- * it with argument values.
+ * Use when you need to represent a client request that already knows the tool
+ * name and asks 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
@@ -1815,8 +1817,8 @@ export class CreateMessageResult extends Schema.Class<CreateMessageResult>(
  *
  * **When to use**
  *
- * Use when an MCP server needs the client to perform model sampling on its
- * behalf.
+ * Use when you need to request model sampling from an MCP client on behalf of a
+ * server.
  *
  * **Details**
  *

package/src/unstable/ai/McpServer.ts

@@ -36,7 +36,7 @@ import * as Queue from "../../Queue.ts"
 import * as RcMap from "../../RcMap.ts"
 import { CurrentLogLevel } from "../../References.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
 import * as Sink from "../../Sink.ts"
 import type { Stdio } from "../../Stdio.ts"
 import * as Stream from "../../Stream.ts"
@@ -808,7 +808,9 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Top>> = {
  *
  * **When to use**
  *
- * Use to add a resource to an existing MCP server from an Effect program.
+ * Use when you are already inside an Effect program with an `McpServer`
+ * service and need to add a concrete resource or URI-template resource
+ * directly.
  *
  * @see {@link resource} for the layer-based resource registration wrapper
  *
@@ -821,7 +823,9 @@ export const registerResource: {
    *
    * **When to use**
    *
-   * Use to add a resource to an existing MCP server from an Effect program.
+   * Use when you are already inside an Effect program with an `McpServer`
+   * service and need to add a concrete resource or URI-template resource
+   * directly.
    *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
@@ -849,7 +853,9 @@ export const registerResource: {
    *
    * **When to use**
    *
-   * Use to add a resource to an existing MCP server from an Effect program.
+   * Use when you are already inside an Effect program with an `McpServer`
+   * service and need to add a concrete resource or URI-template resource
+   * directly.
    *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
@@ -1088,7 +1094,8 @@ export const resource: {
  *
  * **When to use**
  *
- * Use to register an MCP prompt from an Effect program.
+ * Use when you are already inside an Effect program with an `McpServer`
+ * service and need to add a prompt handler directly.
  *
  * **Details**
  *
@@ -1123,8 +1130,8 @@ export const registerPrompt = <
   for (const [name, prop] of Object.entries(props)) {
     args.push({
       name,
-      description: AST.resolveDescription(prop.ast),
-      required: !AST.isOptional(prop.ast)
+      description: SchemaAST.resolveDescription(prop.ast),
+      required: !SchemaAST.isOptional(prop.ast)
     })
   }
   const prompt = new Prompt({