ai 7.0.127 → 7.0.129

package/docs/03-ai-sdk-core/60-telemetry.mdx

@@ -114,7 +114,7 @@ const result = await generateText({
 });
 ```
 
-To disable telemetry globally, do not register any telemetry integrations via the `registerTelemetry()` function.
+Not registering integrations with `registerTelemetry()` prevents delivery to globally registered integrations, but does not disable per-call integrations or Node.js tracing-channel subscribers. To disable telemetry events for a call, including tracing-channel events, pass `telemetry: { isEnabled: false }`. Apply this setting to every call if you want to opt out throughout your application.
 
 ## Telemetry Metadata
 
@@ -157,7 +157,7 @@ const result = await generateText({
 });
 ```
 
-In this example, telemetry integrations receive `runtimeContext` as `{ requestId: 'req_abc' }`. Properties set to `false` or omitted are excluded. If `telemetry.includeRuntimeContext` is omitted, no runtime context properties are included. `telemetry.includeRuntimeContext` is supported by `generateText`, `streamText`, `ToolLoopAgent`, `embed`, `embedMany`, `rerank`, and `experimental_evaluate`.
+In this example, telemetry integrations receive `runtimeContext` as `{ requestId: 'req_abc' }`. Properties set to `false` or omitted are excluded. If `telemetry.includeRuntimeContext` is omitted, no runtime context properties are included. `telemetry.includeRuntimeContext` is supported by `generateText`, `streamText`, `ToolLoopAgent`, `embed`, `embedMany`, `rerank`, and `experimental_decide`.
 
 <Note>
   `telemetry.includeRuntimeContext` only filters telemetry integrations,
@@ -354,6 +354,10 @@ class MyIntegration implements Telemetry {
   async onAbort(event) {
     console.log('Stream aborted after', event.steps.length, 'finished steps');
   }
+
+  async onError(event) {
+    console.error('Generation failed:', event.callId, event.error);
+  }
 }
 
 export function myIntegration(): Telemetry {
@@ -415,27 +419,26 @@ export function myIntegration(): Telemetry {
       description: 'Called when an individual reranking model call completes.',
     },
     {
-      name: 'experimental_onEvaluateStart',
-      type: '(event: Experimental_EvaluateStartEvent) => void | PromiseLike<void>',
-      description: 'Called when an experimental evaluation operation begins.',
+      name: 'experimental_onDecideStart',
+      type: '(event: Experimental_DecideStartEvent) => void | PromiseLike<void>',
+      description: 'Called when an experimental decision operation begins.',
     },
     {
-      name: 'experimental_onEvaluationModelCallStart',
-      type: '(event: Experimental_EvaluationModelCallStartEvent) => void | PromiseLike<void>',
+      name: 'experimental_onDecisionModelCallStart',
+      type: '(event: Experimental_DecisionModelCallStartEvent) => void | PromiseLike<void>',
       description:
-        'Called when the logical evaluation model call begins. The call includes any provider retries.',
+        'Called when the logical decision model call begins. The call includes any provider retries.',
     },
     {
-      name: 'experimental_onEvaluationModelCallEnd',
-      type: '(event: Experimental_EvaluationModelCallEndEvent) => void | PromiseLike<void>',
+      name: 'experimental_onDecisionModelCallEnd',
+      type: '(event: Experimental_DecisionModelCallEndEvent) => void | PromiseLike<void>',
       description:
-        'Called when the logical evaluation model call, including any retries, completes.',
+        'Called when the logical decision model call, including any retries, completes.',
     },
     {
-      name: 'experimental_onEvaluateEnd',
-      type: '(event: Experimental_EvaluateEndEvent) => void | PromiseLike<void>',
-      description:
-        'Called when an experimental evaluation operation completes.',
+      name: 'experimental_onDecideEnd',
+      type: '(event: Experimental_DecideEndEvent) => void | PromiseLike<void>',
+      description: 'Called when an experimental decision operation completes.',
     },
     {
       name: 'onEnd',
@@ -449,10 +452,16 @@ export function myIntegration(): Telemetry {
       description:
         'Called when a streaming text generation operation is aborted before it completes.',
     },
+    {
+      name: 'onError',
+      type: '(event: { callId: string; error: unknown }) => void | PromiseLike<void>',
+      description:
+        'Called when an unrecoverable error occurs. The event identifies the operation and contains the thrown value.',
+    },
   ]}
 />
 
-Experimental evaluation events use the four `experimental_*` callbacks above.
+Experimental decision events use the four `experimental_*` callbacks above.
 They are not included in the stable `onStart` and `onEnd` event unions.
 
 The event types for each method are the same as the corresponding [lifecycle callbacks](/docs/ai-sdk-core/lifecycle-callbacks). See the lifecycle callbacks documentation for the full property reference of each event.
@@ -598,30 +607,30 @@ corresponding input/output recording controls. Raw audio is not captured, so
 transcription input and speech output do not populate message attributes with
 audio content or placeholder audio parts.
 
-#### experimental_evaluate
+#### experimental_decide
 
-For `experimental_evaluate`, the integration records two spans with `CLIENT`
-kind: an **`evaluate {modelId}`** root span for the whole operation and one
-**`evaluate {modelId}`** child span for evaluation model work, including
+For `experimental_decide`, the integration records two spans with `CLIENT`
+kind: a **`decide {modelId}`** root span for the whole operation and one
+**`decide {modelId}`** child span for decision model work, including
 retries. Both include the provider and requested model with
-`gen_ai.operation.name: "evaluate"`. Token
-usage is recorded on the child span. When evaluation attributes are enabled,
+`gen_ai.operation.name: "decide"`. Token
+usage is recorded on the child span. When decision attributes are enabled,
 answers are recorded on both spans so the operation span contains its output.
 
-`evaluate` is an AI SDK-defined custom operation name, not a well-known
+`decide` is an AI SDK-defined custom operation name, not a well-known
 OpenTelemetry GenAI operation. OpenTelemetry permits custom operation names
 when no well-known value describes the operation.
 
 OpenTelemetry's `gen_ai.evaluation.result` event describes the result of
 evaluating a GenAI output for quality or other characteristics. In contrast,
-`experimental_evaluate` can evaluate arbitrary JSON state for classification,
+`experimental_decide` can use arbitrary JSON state for classification,
 routing, scoring, and similar tasks. The integration therefore does not emit a
 `gen_ai.evaluation.result` event.
 
-Evaluation state, questions, and answers also do not have applicable GenAI
-semantic-convention attributes. Enable the `experimental_evaluation`
+Decision state, questions, and answers also do not have applicable GenAI
+semantic-convention attributes. Enable the `experimental_decision`
 supplemental option to record them under AI SDK-specific
-`ai.evaluation.*` attributes.
+`ai.decision.*` attributes.
 
 #### GenAI span details
 
@@ -678,10 +687,10 @@ registerTelemetry(
 
 The callback runs when each span is created and receives:
 
-- `spanType`: the type of span being created (`operation`, `step`, `languageModel`, `tool`, `embedding`, `reranking`, or `experimental_evaluation`).
+- `spanType`: the type of span being created (`operation`, `step`, `languageModel`, `tool`, `embedding`, `reranking`, or `experimental_decision`).
 - `operationId`: the AI SDK operation ID for the current call, such as `ai.generateText` or `ai.streamText`.
 - `callId`: the unique ID for the current AI SDK call.
-- `runtimeContext`: the telemetry-filtered runtime context for text generation, embedding, reranking, and evaluation spans. Text generation spans also reflect updates from `prepareStep`.
+- `runtimeContext`: the telemetry-filtered runtime context for text generation, embedding, reranking, and decision spans. Text generation spans also reflect updates from `prepareStep`.
 
 Custom attributes are merged with AI SDK attributes on the span. AI SDK-owned
 attributes take precedence when a custom attribute uses the same key.
@@ -741,7 +750,7 @@ registerTelemetry(
     providerMetadata: true,
     embedding: true,
     reranking: true,
-    experimental_evaluation: true,
+    experimental_decision: true,
     runtimeContext: true,
     headers: true,
     toolChoice: true,
@@ -756,7 +765,7 @@ The available options are:
 - `providerMetadata`: `ai.response.providerMetadata` on operation, step, and model-call spans.
 - `embedding`: embedding inputs and outputs.
 - `reranking`: rerank input documents and ranking output.
-- `experimental_evaluation`: experimental evaluation state, questions, and answers.
+- `experimental_decision`: experimental decision state, questions, and answers.
 - `runtimeContext`: `ai.settings.context.*`.
 - `headers`: `ai.request.headers.*`.
 - `toolChoice`: `ai.prompt.toolChoice`.

package/docs/03-ai-sdk-core/65-lifecycle-callbacks.mdx

@@ -1,12 +1,12 @@
 ---
 title: Lifecycle Callbacks
-description: Observe AI SDK lifecycle events in generateText, streamText, embed, embedMany, rerank, and experimental_evaluate calls
+description: Observe AI SDK lifecycle events in generateText, streamText, embed, embedMany, rerank, and experimental_decide calls
 ---
 
 # Lifecycle Callbacks
 
 Event callbacks let you run your own code at important points in an AI SDK call.
-You can attach them directly to `generateText`, `streamText`, `embed`, `embedMany`, `rerank`, and `experimental_evaluate` calls to observe what happened, record usage, debug multi-step generations, and monitor tool execution.
+You can attach them directly to `generateText`, `streamText`, `embed`, `embedMany`, `rerank`, and `experimental_decide` calls to observe what happened, record usage, debug multi-step generations, and monitor tool execution.
 
 They are especially useful when you want application-specific logic close to the call site:
 
@@ -452,21 +452,20 @@ const result = await generateText({
   ]}
 />
 
-### `experimental_evaluate`
+### `experimental_decide`
 
 <PropertiesTable
   content={[
     {
       name: 'onStart',
-      type: '(event: Experimental_EvaluateStartEvent) => void | Promise<void>',
+      type: '(event: Experimental_DecideStartEvent) => void | Promise<void>',
       description:
-        'Called when the evaluation operation begins, before the evaluation model is called.',
+        'Called when the decision operation begins, before the decision model is called.',
     },
     {
       name: 'onEnd',
-      type: '(event: Experimental_EvaluateEndEvent) => void | Promise<void>',
-      description:
-        'Called when the evaluation operation completes successfully.',
+      type: '(event: Experimental_DecideEndEvent) => void | Promise<void>',
+      description: 'Called when the decision operation completes successfully.',
     },
   ]}
 />
@@ -1174,10 +1173,10 @@ For `embed`, `value` is a single string. For `embedMany`, `value` is an array of
   ]}
 />
 
-### Evaluation Events
+### Decision Events
 
-Evaluation callbacks are experimental. Their exported types are
-`Experimental_EvaluateStartEvent` and `Experimental_EvaluateEndEvent`.
+Decision callbacks are experimental. Their exported types are
+`Experimental_DecideStartEvent` and `Experimental_DecideEndEvent`.
 
 #### onStart
 
@@ -1186,12 +1185,12 @@ Evaluation callbacks are experimental. Their exported types are
     {
       name: 'callId',
       type: 'string',
-      description: 'Unique identifier for this evaluation call.',
+      description: 'Unique identifier for this decision call.',
     },
     {
       name: 'operationId',
-      type: "'ai.evaluate'",
-      description: 'Evaluation operation identifier.',
+      type: "'ai.decide'",
+      description: 'Decision operation identifier.',
     },
     {
       name: 'runtimeContext',
@@ -1201,22 +1200,22 @@ Evaluation callbacks are experimental. Their exported types are
     {
       name: 'provider',
       type: 'string',
-      description: 'Provider identifier for the evaluation model.',
+      description: 'Provider identifier for the decision model.',
     },
     {
       name: 'modelId',
       type: 'string',
-      description: 'Evaluation model identifier.',
+      description: 'Decision model identifier.',
     },
     {
       name: 'state',
       type: 'string | object | array',
-      description: 'Shared state being evaluated.',
+      description: 'Shared state used to make decisions.',
     },
     {
       name: 'questions',
-      type: 'Readonly<Record<string, Experimental_EvaluationQuestion>>',
-      description: 'Questions being evaluated against the shared state.',
+      type: 'Readonly<Record<string, Experimental_DecisionQuestion>>',
+      description: 'Questions to decide against the shared state.',
     },
     {
       name: 'maxRetries',
@@ -1244,18 +1243,18 @@ Includes every `onStart` field plus:
   content={[
     {
       name: 'answers',
-      type: 'Record<string, Experimental_EvaluationAnswer>',
+      type: 'Record<string, Experimental_DecisionAnswer>',
       description: 'Exactly one typed answer per question ID.',
     },
     {
       name: 'usage',
       type: '{ inputTokens: number | undefined; outputTokens: number | undefined; totalTokens: number | undefined }',
-      description: 'Token usage for the evaluation operation.',
+      description: 'Token usage for the decision operation.',
     },
     {
       name: 'warnings',
       type: 'Array<Warning>',
-      description: 'Warnings from the evaluation model.',
+      description: 'Warnings from the decision model.',
     },
     {
       name: 'rounding',

package/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

@@ -6,8 +6,8 @@ description: Use @ai-sdk/tui with HarnessAgent.
 # Harnesses with Terminal UI
 
 `@ai-sdk/tui` can render harness streams, tool calls, reasoning sections, and
-approval prompts in a terminal. Because `HarnessAgent` requires a session on
-every call, wrap it with a small `AgentTUIAgent` adapter that injects one
+approval prompts in a terminal. Because `HarnessAgent` requires a session for
+`generate` and `stream` calls, wrap it with a small `AgentTUIAgent` adapter that injects one
 session for the lifetime of the terminal UI.
 
 ## Installation

package/docs/04-ai-sdk-ui/21-error-handling.mdx

@@ -12,15 +12,17 @@ These warnings help you fix problems before they cause errors.
 
 ### When Warnings Appear
 
-Warnings are shown in the browser console when:
+Warnings use Node.js `process.emitWarning` when available and `console.warn` in
+browser/edge runtimes. They appear when:
 
 - **Unsupported features**: You use a feature or setting that is not supported by the AI model (e.g., certain options or parameters).
 - **Compatibility warnings**: A feature is used in a compatibility mode, which might work differently or less optimally than intended.
+- **Deprecations**: You use a deprecated API, option, or message format.
 - **Other warnings**: The AI model reports another type of issue, such as general problems or advisory messages.
 
 ### Warning Messages
 
-All warnings start with "AI SDK Warning:" so you can easily find them. For example:
+All warnings include "AI SDK Warning" so you can easily find them. For example:
 
 ```
 AI SDK Warning: The feature "temperature" is not supported by this model
@@ -41,7 +43,8 @@ globalThis.AI_SDK_LOG_WARNINGS = false;
 #### Custom Warning Handler
 
 You can also provide your own function to handle warnings.
-It receives provider id, model id, and a list of warnings.
+It receives a list of warnings and optional provider and model ids. Custom
+handlers receive every warning, including repeated deprecations.
 
 ```ts
 globalThis.AI_SDK_LOG_WARNINGS = ({ warnings, provider, model }) => {
@@ -49,6 +52,28 @@ globalThis.AI_SDK_LOG_WARNINGS = ({ warnings, provider, model }) => {
 };
 ```
 
+### Deprecation Warnings
+
+The default logger emits each deprecation code once per loaded SDK instance.
+In Node.js, these warnings have the type `DeprecationWarning` and a stable
+`AISDK_DEP_*` code, available as `warning.code` on `process.on('warning', handler)`.
+Browser/edge console messages include the code in brackets.
+
+| Code                                     | Deprecated usage / replacement                                             |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| `AISDK_DEP_GENERATE_OBJECT`              | Use `generateText` with `output` instead of `generateObject`.              |
+| `AISDK_DEP_STREAM_OBJECT`                | Use `streamText` with `output` instead of `streamObject`.                  |
+| `AISDK_DEP_EXPERIMENTAL_GENERATE_SPEECH` | Use `generateSpeech` instead of `experimental_generateSpeech`.             |
+| `AISDK_DEP_EXPERIMENTAL_TRANSCRIBE`      | Use `transcribe` instead of `experimental_transcribe`.                     |
+| `AISDK_DEP_TOOL_RESULT_*`                | Use `file` with tagged `data` instead of legacy tool-result content types. |
+| `AISDK_DEP_UI_MESSAGE_RAW_INPUT`         | Use `input` instead of `rawInput` in UI tool parts.                        |
+| `AISDK_DEP_IMAGE_CONTENT_PART`           | Use `file` with an image `mediaType` instead of `image` message parts.     |
+
+Run Node.js with `--throw-deprecation` to fail on deprecated usage,
+`--no-deprecation` to suppress deprecations, or `--trace-deprecation` for stack
+traces. These flags affect all `DeprecationWarning`s, rather than individual
+codes, and apply only to the default Node.js logger.
+
 ## Error Handling
 
 ### Error Helper Object

package/docs/06-advanced/09-multistep-interfaces.mdx

@@ -84,7 +84,7 @@ Tool: bookFlight("BA123", "12th December", ["John Doe", "Jane Doe"])
 Model: Your flight has been booked!
 ```
 
-Before the last tool call, the passenger details needed by the `bookFlight` tool are not available in the application context. As a result, the model asks the user to provide the passenger details before proceeding with the booking.
+After `lookupFlight` returns, the passenger details needed by the `bookFlight` tool are not yet available in the application context. The model asks the user for those details; once the user supplies the names, the model can call `bookFlight`.
 
 Looking up passenger information could've been another tool that the model could've called before calling the `bookFlight` tool assuming that the user is logged into the application. This way, the model does not have to ask the user for the passenger details and can proceed with the booking.
 

package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -455,10 +455,10 @@ To see `generateText` in action, check out [these examples](#examples).
     },
     {
       name: 'reasoning',
-      type: "'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'",
+      type: "'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'",
       isOptional: true,
       description:
-        "Controls how much reasoning the model performs before generating a response. When omitted, the provider's default behavior is used. `'provider-default'` explicitly requests the provider's default. Providers that do not support reasoning will emit a warning. If reasoning-related `providerOptions` are also set, they take precedence and this parameter is ignored. See the [reasoning guide](/docs/ai-sdk-core/reasoning) for provider-specific mapping details.",
+        "Controls how much reasoning the model performs before generating a response. When omitted, the provider's default behavior is used. `'provider-default'` explicitly requests the provider's default. Providers that do not support reasoning will emit a warning. Provider-specific settings take precedence over corresponding mapped fields. Partial configurations may still use portable reasoning to fill missing fields; summary and display settings can be combined with it. See the [reasoning guide](/docs/ai-sdk-core/reasoning) for provider-specific mapping details.",
     },
     {
       name: 'maxRetries',

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -456,10 +456,10 @@ To see `streamText` in action, check out [these examples](#examples).
     },
     {
       name: 'reasoning',
-      type: "'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'",
+      type: "'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'",
       isOptional: true,
       description:
-        "Controls how much reasoning the model performs before generating a response. When omitted, the provider's default behavior is used. `'provider-default'` explicitly requests the provider's default. Providers that do not support reasoning will emit a warning. If reasoning-related `providerOptions` are also set, they take precedence and this parameter is ignored. See the [reasoning guide](/docs/ai-sdk-core/reasoning) for provider-specific mapping details.",
+        "Controls how much reasoning the model performs before generating a response. When omitted, the provider's default behavior is used. `'provider-default'` explicitly requests the provider's default. Providers that do not support reasoning will emit a warning. Provider-specific settings take precedence over corresponding mapped fields. Partial configurations may still use portable reasoning to fill missing fields; summary and display settings can be combined with it. See the [reasoning guide](/docs/ai-sdk-core/reasoning) for provider-specific mapping details.",
     },
     {
       name: 'maxRetries',

package/docs/07-reference/01-ai-sdk-core/14-decide.mdx

@@ -0,0 +1,74 @@
+---
+title: experimental_decide
+description: Decide answers to typed questions against shared state with a decision model.
+---
+
+# `experimental_decide()`
+
+```ts
+import { experimental_decide } from 'ai';
+```
+
+Decides answers to a nonempty map of `choice`, `score`, and `boolean` questions against one
+state. See [Decisions](/docs/ai-sdk-core/decisions) for examples and semantics.
+
+## Parameters
+
+| Parameter         | Type                                             | Description                                                                                                                               |
+| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`           | `Experimental_DecisionModel`                     | Required experimental v4 model instance or a string ID resolved by Gateway or an explicitly configured decision-capable default provider. |
+| `state`           | `string \| object \| array`                      | Required JSON-compatible shared state.                                                                                                    |
+| `questions`       | `Record<string, Experimental_DecisionQuestion>`  | Required nonempty question map.                                                                                                           |
+| `maxRetries`      | `number`                                         | Nonnegative integer; defaults to 2.                                                                                                       |
+| `abortSignal`     | `AbortSignal`                                    | Cancels the decisions request.                                                                                                            |
+| `headers`         | `Record<string, string>`                         | Additional HTTP headers.                                                                                                                  |
+| `providerOptions` | `ProviderOptions`                                | Provider-specific options.                                                                                                                |
+| `telemetry`       | `TelemetryOptions`                               | Telemetry configuration, including per-call integrations, input/output recording, and a function ID.                                      |
+| `runtimeContext`  | `Record<string, unknown>`                        | Context available to lifecycle callbacks and selectively included in telemetry with `telemetry.includeRuntimeContext`.                    |
+| `onStart`         | `(event: Experimental_DecideStartEvent) => void` | Called when the decision operation begins.                                                                                                |
+| `onEnd`           | `(event: Experimental_DecideEndEvent) => void`   | Called when the decision operation completes successfully.                                                                                |
+
+See [Lifecycle Callbacks](/docs/ai-sdk-core/lifecycle-callbacks#experimental_decide)
+for the complete `onStart` and `onEnd` event fields.
+
+## Result
+
+Returns `Promise<Experimental_DecisionResult<QUESTIONS>>`:
+
+- `answers`: One typed answer per question ID, with literal Choice option inference.
+- `usage`: `inputTokens`, `outputTokens`, and `totalTokens`, each possibly undefined.
+- `warnings`: Provider warnings, also passed to the SDK warning logger.
+- `rounding`: Optional provider-declared decimal precision for probabilities and scores.
+- `providerMetadata`: Optional provider-specific metadata.
+- `response`: Timestamp, model ID, and optional response ID, headers, and body.
+
+## Provider specification
+
+`Experimental_DecisionModelV4` is exported from `@ai-sdk/provider` and declares
+`specificationVersion: 'v4'`, `provider`, `modelId`, `supportedQuestionTypes`, and
+`doDecide(options)`. Decision models are isolated from stable `ProviderV4`.
+
+The public core types are `Experimental_DecisionModel`,
+`Experimental_DecisionQuestion`, `Experimental_DecisionAnswer`, and
+`Experimental_DecisionResult`. All decision-specific classes use the
+`Decision` prefix, with `Experimental_` aliases at package boundaries.
+
+## Errors
+
+Unsupported types throw `Experimental_DecisionUnsupportedQuestionTypeError`
+before provider I/O. Invalid inputs throw `InvalidArgumentError`; malformed
+answers throw `InvalidResponseDataError`. Invalid answers are not retried.
+Neither partial results nor missing probability synthesis are supported.
+
+## Model resolution
+
+Use `registry.decisionModel('provider:model')` or
+`customProvider({ decisionModels: { alias: model } }).decisionModel('alias')`
+to resolve models. Strings passed directly to `experimental_decide` use
+`globalThis.AI_SDK_DEFAULT_PROVIDER.decisionModel(id)` when a default provider is
+configured, or Gateway when no default provider is configured.
+
+Resolution errors use the existing `NoSuchModelError` and `NoSuchProviderError`
+classes with `modelType: 'decisionModel'`. Model instances and resolved models
+must implement v4; other versions throw `UnsupportedModelVersionError`.
+See [model resolution examples](/docs/ai-sdk-core/decisions#model-aliases-and-registries).

package/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx

@@ -368,11 +368,24 @@ Returns a Promise that resolves to an `MCPClient` with the following properties
                 'Tool definitions, typically returned by `listTools`.',
             },
             {
-              name: 'schemas',
-              type: 'TOOL_SCHEMAS',
+              name: 'options',
+              type: '{ schemas?: TOOL_SCHEMAS }',
               isOptional: true,
-              description:
-                'Optional schema definitions for compile-time type checking and typed outputs.',
+              description: 'Options for converting the tool definitions.',
+              properties: [
+                {
+                  type: 'options',
+                  parameters: [
+                    {
+                      name: 'schemas',
+                      type: 'TOOL_SCHEMAS',
+                      isOptional: true,
+                      description:
+                        'Optional schema definitions for compile-time type checking and typed outputs.',
+                    },
+                  ],
+                },
+              ],
             },
           ],
         },
@@ -641,6 +654,47 @@ The client throws `MCPClientError` for:
 - Missing server capabilities
 - Connection failures
 
+Import `MCPClientError` from `@ai-sdk/mcp` and use its `isInstance` method to
+safely narrow unknown errors:
+
+```typescript
+import { createMCPClient, MCPClientError } from '@ai-sdk/mcp';
+
+try {
+  await createMCPClient({
+    transport: {
+      type: 'http',
+      url: 'https://your-server.com/mcp',
+    },
+  });
+} catch (error) {
+  if (MCPClientError.isInstance(error)) {
+    if (error.statusCode === 401 || error.statusCode === 403) {
+      // Authentication or authorization must be fixed before retrying.
+      throw error;
+    }
+
+    // Inspect error.code and error.statusCode according to your application's policy.
+  }
+
+  throw error;
+}
+```
+
+The error exposes the optional `code`, `statusCode`, `url`, and `responseBody`
+properties. `code` is the JSON-RPC application error code. `statusCode`, `url`,
+and `responseBody` contain HTTP transport context when it is available. They
+are `undefined` for failures without an HTTP response, such as network errors,
+timeouts, aborted requests, and stdio transport failures.
+
+`MCPClientError` also represents configuration and protocol errors, so its
+type or a missing `statusCode` alone does not indicate a retryable failure.
+OAuth failures can instead throw the separately exported `UnauthorizedError`
+or `MCPClientOAuthError`.
+
+Avoid logging `url` or `responseBody` without redacting sensitive endpoint,
+query parameter, or server response data.
+
 For tool execution, errors are propagated as `CallToolError` errors.
 
 For unknown errors, the client exposes an `onUncaughtError` callback that can be used to manually log or handle errors that are not covered by known error types.

package/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx

@@ -299,20 +299,20 @@ The `createProviderRegistry` function returns a `Provider` instance. It has the
   ]}
 />
 
-## Experimental evaluation models
+## Experimental decision models
 
-The inferred return type also exposes `evaluationModel('providerId:modelId')`,
-returning `Experimental_EvaluationModelV4`. The provider must expose an
-`evaluationModel` factory. Custom separators and model ID
+The inferred return type also exposes `decisionModel('providerId:modelId')`,
+returning `Experimental_DecisionModelV4`. The provider must expose an
+`decisionModel` factory. Custom separators and model ID
 inference work as they do for video models. Language and image middleware do not
-wrap evaluation models. `ProviderRegistryProvider` remains a stable interface;
-use the inferred return type or `Experimental_EvaluationProviderRegistry` to
-retain experimental evaluation access.
+wrap decision models. `ProviderRegistryProvider` remains a stable interface;
+use the inferred return type or `Experimental_DecisionProviderRegistry` to
+retain experimental decision access.
 
-Unavailable evaluation capabilities or models throw `NoSuchModelError` with
-`modelType: 'evaluationModel'`; unknown registry providers throw
+Unavailable decision capabilities or models throw `NoSuchModelError` with
+`modelType: 'decisionModel'`; unknown registry providers throw
 `NoSuchProviderError`. These capabilities are structural extensions and are not
-added to the stable `ProviderV4` contract. Direct evaluation string IDs default
+added to the stable `ProviderV4` contract. Direct decision string IDs default
 to Gateway when no default provider is configured.
-See [Evaluation](/docs/ai-sdk-core/evaluation#model-aliases-and-registries)
+See [Decisions](/docs/ai-sdk-core/decisions#model-aliases-and-registries)
 for runnable usage patterns.

package/docs/07-reference/01-ai-sdk-core/42-custom-provider.mdx

@@ -202,20 +202,20 @@ The `customProvider` function returns a `Provider` instance. It has the followin
   ]}
 />
 
-## Experimental evaluation models
+## Experimental decision models
 
-Pass `evaluationModels: Record<string, Experimental_EvaluationModel>` to define
-aliases for evaluation model instances or string IDs. The returned provider adds
-`evaluationModel(alias): Experimental_EvaluationModelV4`. String aliases resolve
+Pass `decisionModels: Record<string, Experimental_DecisionModel>` to define
+aliases for decision model instances or string IDs. The returned provider adds
+`decisionModel(alias): Experimental_DecisionModelV4`. String aliases resolve
 through Gateway by default, or an explicitly configured default provider with
-an `evaluationModel` method. Unknown aliases use the fallback provider's evaluation
+a `decisionModel` method. Unknown aliases use the fallback provider's decision
 factory when available; model failures and unsupported questions do not trigger
 substitution.
 
-Unavailable evaluation capabilities or models throw `NoSuchModelError` with
-`modelType: 'evaluationModel'`; unknown registry providers throw
+Unavailable decision capabilities or models throw `NoSuchModelError` with
+`modelType: 'decisionModel'`; unknown registry providers throw
 `NoSuchProviderError`. These capabilities are structural extensions and are not
-added to the stable `ProviderV4` contract. Direct evaluation string IDs default
+added to the stable `ProviderV4` contract. Direct decision string IDs default
 to Gateway when no default provider is configured.
-See [Evaluation](/docs/ai-sdk-core/evaluation#model-aliases-and-registries)
+See [Decisions](/docs/ai-sdk-core/decisions#model-aliases-and-registries)
 for runnable usage patterns.