@toolgrain/mcp 0.1.0 → 0.1.2

package/src/auth/audience.ts

@@ -1,6 +1,14 @@
 import { AuthError } from "./errors.js";
 
-/** Validate the audience of an already verified token without disclosing its claims. */
+/**
+ * Require an already verified token's audience to contain the exact MCP resource URL.
+ * This checks only audience membership, not signatures, issuers, expiry, or revocation.
+ *
+ * @param audience - Verified `aud` claim: a string or array of strings.
+ * @param resource - Expected resource URL to match exactly.
+ * @throws `AuthError` with `invalid_token` for missing, malformed, or mismatched audiences.
+ * Missing and mismatched claims include public guidance without disclosing received claims.
+ */
 export function validateTokenAudience(
   audience: unknown,
   resource: string,

package/src/auth/context.ts

@@ -3,7 +3,15 @@ import type { AuthIdentity, AuthReadonly } from "./types.js";
 
 const key = Symbol.for("@toolgrain/mcp/auth-context/v1");
 
-/** Typed integrations bind their accessor to a stable, registered provider symbol. */
+/**
+ * Create a synchronous accessor for a provider's already verified identity snapshot.
+ * Reading the identity performs no verification, network request, or lazy resolution.
+ *
+ * @typeParam Identity - Plain identity data returned by the matching provider.
+ * @param type - The provider's identity symbol; use `Symbol.for()` across package copies.
+ * @returns An accessor accepting a tool context and returning its deeply frozen identity.
+ * The accessor throws if that context has no identity for this provider.
+ */
 export function createAuthAccessor<Identity extends object>(type: symbol) {
   return (ctx: ToolContext): AuthReadonly<Identity> => {
     const auth = Object.getOwnPropertyDescriptor(ctx, key)?.value as

package/src/auth/errors.ts

@@ -1,3 +1,4 @@
+/** Public authorization failure categories mapped by HTTP adapters to 400, 401, 403, or 503. */
 export type AuthErrorCode =
   | "invalid_request"
   | "invalid_token"
@@ -9,11 +10,22 @@ const brand = Symbol.for("@toolgrain/mcp/AuthError/v1");
 /** Only an explicitly public description is exposed; provider causes stay private. */
 export class AuthError extends Error {
   readonly [brand] = true;
+  /** Explicitly client-visible guidance; omitted descriptions keep HTTP responses generic. */
   readonly description?: string | undefined;
 
+  /**
+   * Create an authorization failure with optional public guidance and a private cause.
+   *
+   * @param code - Authorization failure category used by HTTP adapters.
+   * @param options - Optional public description and private standard `Error` options.
+   */
   constructor(
+    /** Failure category; determines the default message and HTTP status. */
     readonly code: AuthErrorCode,
-    options?: ErrorOptions & { description?: string },
+    options?: ErrorOptions & {
+      /** Public message included in HTTP error bodies and challenges; never include secrets. */
+      description?: string;
+    },
   ) {
     super(
       options?.description ??
@@ -30,6 +42,12 @@ export class AuthError extends Error {
   }
 }
 
+/**
+ * Recognize branded authorization errors, including those from compatible package copies.
+ *
+ * @param value - Any thrown or returned value to inspect.
+ * @returns Whether the value is an `Error` with Toolgrain's authorization-error brand.
+ */
 export function isAuthError(value: unknown): value is AuthError {
   return value instanceof Error && Reflect.get(value, brand) === true;
 }

package/src/auth/types.ts

@@ -1,27 +1,48 @@
 /** Implemented by integrations; the HTTP adapter supplies the resolved resource. */
 export interface AuthProvider<Identity extends object = object> {
+  /** Stable provider identity used by `createAuthAccessor()`; use `Symbol.for()` across copies. */
   readonly type: symbol;
+  /** Canonical public MCP resource URL; omission lets the HTTP adapter infer it per request. */
   readonly resource?: string;
+  /** Nonempty list of trusted authorization-server URLs advertised in public metadata. */
   readonly authorizationServers: readonly string[];
+  /**
+   * Verify token authenticity, validity, and resource audience before returning plain identity data.
+   * The server copies and deeply freezes the identity before exposing it to handlers.
+   *
+   * @param accessToken - Raw bearer token without its scheme prefix.
+   * @param options - Resolved resource and request cancellation signal.
+   * @returns Verified plain data; credentials and SDK methods should not be included.
+   * @throws `AuthError` for expected rejections; unexpected failures remain private diagnostics.
+   */
   verify(accessToken: string, options: AuthVerifyOptions): Promise<Identity>;
 }
 
+/** Resource and cancellation information supplied to an authorization provider. */
 export interface AuthVerifyOptions {
+  /** Shared cancellation for verification, body reading, execution, and server shutdown. */
   readonly signal: AbortSignal;
+  /** Expected token audience, after applying any provider resource override. */
   readonly resource: string;
 }
 
+/** Public authorization configuration copied by `Server.getAuthMetadata()`. */
 export interface AuthMetadata {
+  /** Canonical public resource URL, or absent when inferred from the current HTTP request. */
   readonly resource?: string;
+  /** Trusted authorization-server URLs advertised by protected-resource metadata. */
   readonly authorizationServers: readonly string[];
 }
 
 /** An opaque, single-use authorization for one server invocation. Always dispose it. */
 export interface AuthScope {
+  /** Cancellation signal spanning verification and the authorized invocation. */
   readonly signal: AbortSignal;
+  /** Release request bookkeeping and prevent future use; safe to call more than once. */
   dispose(): void;
 }
 
+/** Recursively readonly view of the plain identity snapshot exposed by auth accessors. */
 export type AuthReadonly<T> = T extends readonly (infer Item)[]
   ? readonly AuthReadonly<Item>[]
   : T extends object

package/src/auth/url.ts

@@ -1,4 +1,12 @@
-/** Canonical external URL; HTTP is permitted only for local development. */
+/**
+ * Validate an auth configuration URL, returning the original string unchanged.
+ * Requires HTTPS, except HTTP on `localhost`, `127.0.0.1`, or `[::1]` for development.
+ * Credentials, whitespace, control characters, queries, and fragments are rejected.
+ *
+ * @param value - Authorization-server, signing-key, or canonical resource URL.
+ * @returns The supplied URL after validation; no normalization is applied.
+ * @throws `TypeError` for an invalid or disallowed URL.
+ */
 export function authUrl(value: string): string {
   const url = new URL(value);
   if (

package/src/context/definition.ts

@@ -12,6 +12,7 @@ export interface ContextBinding {
 
 /** Erase values for heterogeneous registrations without exposing unsafe overrides. */
 export abstract class RegisteredContextProvider {
+  /** Nonempty diagnostic label; distinct providers may share a name without sharing identity. */
   abstract readonly name: string;
   abstract readonly use: (ctx: ToolContext) => Promise<unknown>;
 
@@ -26,8 +27,23 @@ Object.defineProperty(RegisteredContextProvider.prototype, brand, {
 
 /** An opaque, invariant value contract; use createContext() and provide() for bindings. */
 export abstract class ContextProvider<Value> extends RegisteredContextProvider {
+  /**
+   * Read the context's lazy value, sharing one promise across concurrent readers.
+   * Always returns a promise, even for synchronous resolvers. Values remain unchanged
+   * and application-owned. Missing bindings, cycles, cancellation, and resolver failures reject.
+   *
+   * @param ctx - Context supplied by Toolgrain to a handler/resolver or made with `toolContext()`.
+   * @returns This context's cached value or failure for the provider identity.
+   */
   abstract readonly use: (ctx: ToolContext) => Promise<Value>;
   // A function property prevents widening Value and then overriding it incompatibly.
+  /**
+   * Create an override with the same identity and inferred value contract.
+   * Register the override instead of the original; existing accessors find it automatically.
+   *
+   * @param resolve - Replacement factory, invoked only on first access in each context.
+   * @returns A frozen provider binding without changing this provider or other registrations.
+   */
   abstract readonly provide: (
     resolve: (ctx: ToolContext) => Value | PromiseLike<Value>,
   ) => ContextProvider<Value>;
@@ -60,9 +76,20 @@ class Provider<Value> extends ContextProvider<Value> {
   };
 }
 
-/** Infer the resolved value type, including asynchronous factories. */
+/**
+ * Define a lazy provider with an inferred value type, including asynchronous factories.
+ * Register it in a server or `toolContext()` before calling its `use` accessor.
+ * Identity belongs to the definition, not its name. Resources remain application-owned;
+ * Toolgrain does not copy, freeze, or automatically dispose the resolved value.
+ *
+ * @param options - Diagnostic name and factory for the value.
+ * @returns A frozen provider with a typed async accessor and override factory.
+ * @throws `TypeError` if the name is empty or the resolver is not a function.
+ */
 export function createContext<Value>(options: {
+  /** Nonempty diagnostic label, used in missing-provider and dependency-cycle errors. */
   name: string;
+  /** Lazy factory; may await other registered providers and should pass `ctx.signal` to work. */
   resolve: (ctx: ToolContext) => Value;
 }): ContextProvider<Awaited<Value>> {
   if (

package/src/diagnostics.ts

@@ -2,7 +2,9 @@ import type { ToolRequest } from "./tools/context.js";
 
 /** Private diagnostics for an unexpected tool failure; no arguments or auth data are added. */
 export interface ToolErrorDetails {
+  /** Exposed registration name of the tool whose execution failed. */
   readonly toolName: string;
+  /** Frozen request metadata; arguments and authorization credentials are not added. */
   readonly request: ToolRequest;
 }
 

package/src/server.ts

@@ -21,39 +21,99 @@ import {
   type Transport,
 } from "./transport.js";
 
+/** Tool registrations, identity, and shared configuration for an MCP server. */
 export interface ServerOptions<Tools extends ToolMap = ToolMap> {
+  /** Server implementation name advertised to clients. */
   name: string;
+  /** Application version advertised to clients; independent of the protocol revision. */
   version: string;
+  /** Tools made with `tool()`; each registration key becomes its exposed tool name. */
   tools: Tools;
+  /** Optional usage instructions advertised to clients during discovery or initialization. */
   instructions?: string;
-  /** Tool failures include frozen tool/request details; other diagnostics omit them. */
+  /**
+   * Receives original unexpected failures for private diagnostics. Tool failures
+   * include frozen tool/request details; auth and transport failures pass only
+   * the error. Throws and rejected promises from this callback are ignored.
+   */
   onError?: ErrorHandler;
+  /** Eager endpoint authorization; requires a request transport rather than stdio. */
   auth?: AuthProvider;
+  /** Lazy providers or typed overrides available to handlers; registration order is irrelevant. */
   context?: readonly RegisteredContextProvider[];
 }
 
+/** Request-local settings for direct protocol dispatch through `Server.handle()`. */
 export interface HandleOptions {
+  /** Cooperative cancellation signal; handlers must observe it, and late responses are suppressed. */
   signal?: AbortSignal;
+  /**
+   * Protocol revision selected by the adapter. If omitted, dispatch is modern except
+   * for legacy initialization requests without explicit protocol-version metadata.
+   */
   protocolVersion?: SupportedProtocolVersion;
+  /** Single-use scope issued by this server's `authorize()`; dispose it in `finally`. */
   auth?: AuthScope;
 }
 
+/** An MCP dispatcher with one optional transport attachment and terminal shutdown. */
 export interface Server {
+  /**
+   * Dispatch a decoded JSON value, including tool validation and MCP result conversion.
+   * This independent request path does not retain initialization or session state.
+   *
+   * @param message - Untrusted, already JSON-decoded protocol message.
+   * @param options - Cancellation, protocol selection, and any required authorization scope.
+   * @returns A protocol response, or `undefined` for ignored or cancelled messages.
+   * @throws If the server is closed or its required authorization scope is invalid.
+   */
   handle(
     message: unknown,
     options?: HandleOptions,
   ): Promise<ProtocolResponse | undefined>;
+  /** Return copied wire descriptions using registration keys as tool names. */
   getToolDefinitions(): ProtocolTool[];
+  /** Return copied public auth configuration, or `undefined` for an unprotected server. */
   getAuthMetadata(): AuthMetadata | undefined;
+  /**
+   * Verify a bearer token before reading a request body or invoking tools.
+   * The identity is copied and deeply frozen before a server-bound scope is issued.
+   *
+   * @param accessToken - Raw bearer token, without the `Bearer ` prefix.
+   * @param options - Resource audience and cancellation settings for this request.
+   * @returns A single-use scope; the caller must dispose it in `finally`.
+   * @throws For rejected credentials, provider failures, cancellation, or a closed server.
+   */
   authorize(
     accessToken: string,
-    options: { resource: string; signal?: AbortSignal },
+    options: {
+      /** Public MCP resource URL; a configured provider resource takes precedence. */
+      resource: string;
+      /** Cancels verification and remains active while the returned scope is in use. */
+      signal?: AbortSignal;
+    },
   ): Promise<AuthScope>;
+  /**
+   * Attach and start one single-use transport, resolving when startup completes.
+   * Auth-configured servers require a request transport. A closed server cannot restart.
+   *
+   * @param transport - An unused transport, including one from a compatible package copy.
+   * @throws If attachment or startup fails, or the transport is already owned.
+   */
   listen(transport: Transport | RequestTransport): Promise<void>;
+  /** Abort active work and close the attached transport; repeated or nested calls are safe. */
   close(): Promise<void>;
 }
 
-/** Compose the tool adapter, MCP dispatcher, and transport connection. */
+/**
+ * Create a server from reusable tools, optional auth, and lazy context providers.
+ * Registration validates tool names, metadata, and exposable schemas immediately.
+ * Creating the server does not start a transport or resolve context providers.
+ *
+ * @param options - Server identity and application-owned tool/provider registrations.
+ * @returns An independent server ready for direct dispatch or `listen()`.
+ * @throws For invalid registrations, tool schemas, or authorization configuration.
+ */
 export function createServer<const Tools extends ToolMap>(
   options: ServerOptions<Tools>,
 ): Server {

package/src/tools/context.ts

@@ -21,14 +21,19 @@ import type { DeepReadonly } from "./json-value.js";
 
 /** What the client reported about itself; unverified, so not a basis for security decisions. */
 export interface ToolClient {
+  /** Copied, deeply frozen implementation details supplied by the client, when available. */
   readonly info?: DeepReadonly<Implementation | LegacyImplementation>;
+  /** Copied, deeply frozen capability claims supplied by the client, when available. */
   readonly capabilities?: DeepReadonly<
     ClientCapabilities | LegacyClientCapabilities
   >;
 }
 
+/** Copied, immutable protocol metadata for one invocation; client claims remain unverified. */
 export interface ToolRequest {
+  /** JSON-RPC request identifier; identical IDs can occur in independent contexts. */
   readonly id: RequestId;
+  /** Supported protocol revision selected for this invocation. */
   readonly protocolVersion: SupportedProtocolVersion;
   /** Absent when the era and transport carry no client information, such as legacy HTTP. */
   readonly client?: ToolClient;
@@ -36,19 +41,32 @@ export interface ToolRequest {
   readonly meta: Readonly<Record<string, unknown>>;
 }
 
+/** Per-invocation data passed to tool handlers and lazy context resolvers. */
 export interface ToolContext {
   /** Aborts when the client cancels or disconnects, or the transport or server closes. */
   readonly signal: AbortSignal;
+  /** Frozen request metadata; contains no verified authorization identity. */
   readonly request: ToolRequest;
 }
 
+/** Optional metadata, cancellation, and provider bindings for a direct-call context. */
 export interface ToolContextOptions {
+  /** Caller-owned cancellation signal; defaults to a fresh, non-aborted signal. */
   signal?: AbortSignal;
+  /** Request fields to override; defaults are ID `0`, the modern revision, and empty metadata. */
   request?: Partial<ToolRequest>;
+  /** Providers or overrides available through their accessors; defaults to no registrations. */
   context?: readonly RegisteredContextProvider[];
 }
 
-/** Build a context for calling a definition's `execute` directly, for example in tests. */
+/**
+ * Build an unauthenticated context for direct `execute()` calls, for example in tests.
+ * Request metadata is copied and deeply frozen; each call creates a fresh provider cache.
+ * Direct execution still bypasses server authorization, validation, and MCP conversion.
+ *
+ * @param options - Optional signal, request metadata, and provider registrations.
+ * @returns A context accepted by Toolgrain's provider accessors.
+ */
 export function toolContext(options: ToolContextOptions = {}): ToolContext {
   // Default each field separately so an explicit undefined cannot replace a default.
   const {

package/src/tools/definition.ts

@@ -20,16 +20,30 @@ export const TOOL_METADATA_KEYS = [
   "_meta",
 ] as const;
 
+/**
+ * Optional client-facing tool title, description, behavior hints, icons, and `_meta`.
+ * Accepts readonly authoring data; registration checks JSON compatibility and copies
+ * metadata for wire descriptions. Hints describe behavior rather than enforce policy.
+ */
 export type ToolMetadata = DeepReadonly<
   Pick<ProtocolTool, (typeof TOOL_METADATA_KEYS)[number]>
 >;
 
+/**
+ * Authoring contract for `tool()`; handler input uses the parsed Zod output type.
+ *
+ * @typeParam Schema - Zod 4 Classic or Mini input schema with an exposable object root.
+ * @typeParam Result - Raw handler return value, including a promise-like value.
+ * @typeParam Output - Optional Zod output schema; the handler returns its input type.
+ */
 export interface ToolDefinition<
   Schema extends core.$ZodType,
   Result,
   Output extends core.$ZodType = never,
 > extends ToolMetadata {
+  /** Input schema, parsed asynchronously by the server before the handler runs. */
   readonly input: Schema;
+  /** Optional output schema, parsed asynchronously before successful result conversion. */
   readonly output?: Output;
   /** Raw handler; server invocation performs validation and result conversion. */
   readonly execute: (input: core.output<Schema>, ctx: ToolContext) => Result;
@@ -68,21 +82,38 @@ export function isRegisteredTool(value: unknown): value is RegisteredTool {
   );
 }
 
+/**
+ * Frozen, reusable tool definition returned by `tool()`. Register the same definition
+ * under different keys or create typed variants by passing a spread through `tool()` again.
+ * Direct `execute()` calls remain raw application calls.
+ *
+ * @typeParam Schema - Input schema whose parsed output is passed to the handler.
+ * @typeParam Result - Raw handler return type, before server output parsing and conversion.
+ * @typeParam Output - Output schema when declared by the definition.
+ */
 export class Tool<
   Schema extends core.$ZodType,
   Result,
   Output extends core.$ZodType = core.$ZodType,
 > extends RegisteredTool {
+  /** Zod input schema used by server validation; defaults and transforms run asynchronously. */
   declare readonly input: Schema;
+  /** Optional Zod output schema used by server result validation. */
   declare readonly output?: Output;
+  /** Raw handler; direct calls bypass authorization, input/output parsing, and MCP conversion. */
   declare readonly execute: (
     input: core.output<Schema>,
     ctx: ToolContext,
   ) => Result;
+  /** Optional human-readable title advertised to clients. */
   declare readonly title?: string;
+  /** Optional description explaining the tool's purpose and behavior to clients. */
   declare readonly description?: string;
+  /** Client-facing behavior hints; Toolgrain does not enforce their assertions. */
   declare readonly annotations?: NonNullable<ToolMetadata["annotations"]>;
+  /** Optional client-facing icon descriptors, with readonly authoring inputs. */
   declare readonly icons?: NonNullable<ToolMetadata["icons"]>;
+  /** Optional JSON-compatible protocol metadata advertised with the tool. */
   declare readonly _meta?: NonNullable<ToolMetadata["_meta"]>;
 
   constructor(definition: ToolDefinition<Schema, Result, core.$ZodType>) {
@@ -116,12 +147,21 @@ type ToolDefinitionWithoutOutput<Schema extends core.$ZodType, Result> = Omit<
   ToolDefinition<Schema, Result>,
   "execute"
 > & {
+  /** Raw handler accepting parsed input; server invocation validates its JSON-compatible result. */
   readonly execute: (
     input: core.output<Schema>,
     ctx: ToolContext,
   ) => Result & JsonSafeOutput<Result>;
 };
 
+/**
+ * Define a frozen tool with asynchronously validated input and declared output.
+ * Successful rich results must include `structuredContent`; explicit text-only errors may omit it.
+ *
+ * @param definition - Zod schemas, a handler returning the output schema's input type, and metadata.
+ * @returns A reusable tool retaining input, output, and handler inference.
+ * Its `execute` property stays raw; server invocation performs validation and conversion.
+ */
 export function tool<
   Schema extends core.$ZodType,
   Output extends core.$ZodType,
@@ -130,9 +170,20 @@ export function tool<
     | PromiseLike<OutputResult<NoInfer<Output>>>,
 >(
   definition: ToolDefinition<Schema, Result, Output> & {
+    /** Required output schema for this overload; parses handler data before MCP conversion. */
     readonly output: Output;
   },
-): Tool<Schema, Result, Output> & { readonly output: Output };
+): Tool<Schema, Result, Output> & {
+  /** Declared output schema, retained as required on the inferred tool type. */
+  readonly output: Output;
+};
+/**
+ * Define a frozen tool without an output schema, preserving the handler's inferred return type.
+ * Ordinary strings and JSON values become MCP results; use `mcpResult()` for rich content.
+ *
+ * @param definition - Zod input schema, a JSON-compatible or explicit-result handler, and metadata.
+ * @returns A reusable tool whose direct `execute()` calls bypass server validation and conversion.
+ */
 export function tool<Schema extends core.$ZodType, Result>(
   definition: ToolDefinitionWithoutOutput<Schema, Result>,
 ): Tool<Schema, Result, never>;

package/src/tools/name.ts

@@ -1,5 +1,10 @@
+/** Registration error for a name outside 1–128 ASCII letters, digits, underscores, hyphens, or dots. */
 export class ToolNameError extends Error {
-  constructor(public readonly toolName: string) {
+  /** @param toolName - Invalid registration key that could not be exposed as an MCP tool name. */
+  constructor(
+    /** Invalid exposed registration name. */
+    public readonly toolName: string,
+  ) {
     super(
       `Invalid MCP tool name: ${JSON.stringify(toolName)}. Use 1–128 ASCII letters, digits, underscores, hyphens, or dots.`,
     );

package/src/tools/registry.ts

@@ -7,6 +7,10 @@ import {
 } from "./definition.js";
 import { ToolInputError, UnknownToolError } from "./errors.js";
 
+/**
+ * Tools indexed by exposed MCP names. Values must be frozen definitions made with `tool()`;
+ * names come from these keys, not from a definition's variable name or title.
+ */
 export type ToolMap = Record<string, RegisteredTool>;
 
 export interface ToolEntry extends ToolMetadata {

package/src/tools/rich-result.ts

@@ -1,18 +1,30 @@
 import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
 import type { DeepReadonly, JsonCompatible } from "./json-value.js";
 
+/** Explicit MCP content and optional structured data, wrapped with `mcpResult()`. */
 export interface McpResultOptions<Structured = unknown> {
+  /** Content blocks for the client; readonly authoring arrays are accepted. */
   content: readonly DeepReadonly<ContentBlock>[];
+  /** JSON-compatible data; required for successful rich results with a declared output schema. */
   structuredContent?: Structured & JsonCompatible<NoInfer<Structured>>;
+  /** Marks an expected, client-visible tool failure; omitted or false indicates success. */
   isError?: boolean;
+  /** Optional protocol result metadata, distinct from application structured data. */
   _meta?: MetaObject;
 }
 
 // Registered symbols let duplicate package copies recognize each other's results.
 const RESULT_BRAND = Symbol.for("@toolgrain/mcp/result@1");
 
+/**
+ * Branded rich-result wrapper recognized by compatible Toolgrain package copies.
+ * Use `mcpResult()` to construct one; a plain object with the same fields remains application data.
+ */
 export class McpResult<Structured> {
-  constructor(readonly value: McpResultOptions<Structured>) {
+  constructor(
+    /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
+    readonly value: McpResultOptions<Structured>,
+  ) {
     Object.freeze(this);
   }
 
@@ -32,34 +44,84 @@ export function isMcpResult(value: unknown): value is McpResult<unknown> {
   );
 }
 
+/** Explicit, client-visible tool error; structured data may be omitted for text-only errors. */
 export type McpErrorResult<Structured = never> = McpResult<Structured> & {
-  readonly value: McpResultOptions<Structured> & { isError: true };
+  /** Envelope statically marked as an error. */
+  readonly value: McpResultOptions<Structured> & {
+    /** Explicit expected-failure marker, preserved in the MCP result. */
+    isError: true;
+  };
 };
 
 /** A result whose structured data is present, as required by an output schema. */
 export type McpStructuredResult<Structured> = McpResult<Structured> & {
+  /** Envelope with required application structured data. */
   readonly value: McpResultOptions<Structured> & {
+    /** Structured value validated against the tool's output schema when one is declared. */
     structuredContent: Structured;
   };
 };
 
-/** Explicitly return MCP content. Ordinary objects always remain application data. */
+/**
+ * Explicitly return rich MCP content; ordinary result-shaped objects remain application data.
+ * This overload wraps a public tool error that also supplies structured data.
+ * @param value - Error content and JSON-compatible data, parsed by any declared output schema.
+ * @returns A branded result typed as both an error and a structured result.
+ */
 export function mcpResult<Structured = never>(
   value: McpResultOptions<Structured> & {
+    /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
+    /** Structured error data, subject to output-schema validation when declared. */
     structuredContent: Structured;
   },
 ): McpErrorResult<Structured> & McpStructuredResult<Structured>;
+/**
+ * Wrap a text/content-only public tool error, allowed even when the tool declares output.
+ * @param value - Explicit error content without structured application data.
+ * @returns A branded error result whose `isError` flag is statically true.
+ */
 export function mcpResult(
-  value: McpResultOptions<never> & { isError: true },
+  value: McpResultOptions<never> & {
+    /** Mark this result as an expected, client-visible tool failure. */
+    isError: true;
+  },
 ): McpErrorResult<never>;
+/**
+ * Wrap a public tool error with an optional structured-data contract.
+ * @param value - Error content and any JSON-compatible structured data.
+ * @returns A branded error result; provided structured data still undergoes output validation.
+ */
 export function mcpResult<Structured>(
-  value: McpResultOptions<Structured> & { isError: true },
+  value: McpResultOptions<Structured> & {
+    /** Mark this result as an expected, client-visible tool failure. */
+    isError: true;
+  },
 ): McpErrorResult<Structured>;
+/**
+ * Wrap rich content with required structured application data.
+ * @param value - Client content and JSON-compatible data; a successful output-schema result needs both.
+ * @returns A branded structured result; the server validates and converts it for the selected revision.
+ */
 export function mcpResult<Structured>(
-  value: McpResultOptions<Structured> & { structuredContent: Structured },
+  value: McpResultOptions<Structured> & {
+    /** Required application data, parsed by the declared output schema when present. */
+    structuredContent: Structured;
+  },
 ): McpStructuredResult<Structured>;
+/**
+ * Wrap explicit client content without structured application data.
+ * @param value - Rich content; successful results of this form require a tool without an output schema.
+ * @returns A branded MCP result. Ordinary result-shaped objects are not treated as rich results.
+ */
 export function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+/**
+ * Explicitly return MCP content instead of ordinary application JSON.
+ * The server validates the envelope, parses supplied output data, and converts it for the protocol revision.
+ *
+ * @param value - Content blocks, optional structured data, an error marker, and protocol metadata.
+ * @returns A frozen result wrapper; content is checked during server invocation.
+ */
 export function mcpResult<Structured = never>(
   value: McpResultOptions<Structured>,
 ): McpResult<Structured>;

package/src/tools/schema.ts

@@ -24,10 +24,18 @@ const metadata = z.strictObject({
   _meta: object.optional(),
 });
 
+/** Registration error wrapping a schema-conversion or metadata-validation failure. */
 export class ToolSchemaError extends Error {
+  /**
+   * @param toolName - Exposed registration name whose description could not be built.
+   * @param cause - Original schema or metadata failure, retained as the error's cause.
+   * @param schemaKind - Failing part of the description; defaults to `input`.
+   */
   constructor(
+    /** Exposed registration name whose schema or metadata failed. */
     public readonly toolName: string,
     cause: unknown,
+    /** Whether input conversion, output conversion, or metadata validation failed. */
     public readonly schemaKind: "input" | "output" | "metadata" = "input",
   ) {
     super(`Cannot expose ${schemaKind} schema for tool: ${toolName}`, {