@mastra/mcp-docs-server 1.3.7-alpha.1 → 1.3.7-alpha.5

package/.docs/reference/datasets/dataset.md

@@ -60,7 +60,7 @@ const history = await dataset.getItemHistory({ itemId: 'item-id' })
 
 ## Access
 
-`Dataset` isn't instantiated directly. Obtain one via `DatasetsManager`:
+Obtain a `Dataset` through `DatasetsManager`, which resolves the dataset and applies tenancy scope:
 
 ```typescript
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
@@ -68,6 +68,8 @@ const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 const dataset = await mastra.datasets.create({ name: 'My dataset' })
 ```
 
+`Dataset` also has a public constructor (`new Dataset(id, mastra)`) that skips the manager's lookup and tenancy scoping.
+
 ## Properties
 
 For the full dataset record (name, description, schemas, version, timestamps), call [`dataset.getDetails()`](https://mastra.ai/reference/datasets/getDetails).

package/.docs/reference/datasets/finalizeExperiment.md

@@ -6,7 +6,7 @@
 
 **Added in:** `@mastra/core@1.61.0`
 
-Finalizes a caller-driven experiment created with [`createExperiment()`](https://mastra.ai/reference/datasets/createExperiment), with or without a target. Mastra computes the final counts server-side from the persisted result rows and marks the experiment `'completed'`. The caller never tracks completion bookkeeping.
+Finalizes a caller-driven experiment created with [`createExperiment()`](https://mastra.ai/reference/datasets/createExperiment), with or without a target. Mastra computes the final counts server-side from the persisted result rows and marks the experiment `'completed'`. An experiment that's already `'failed'` is returned unchanged and stays failed. The caller never tracks completion bookkeeping.
 
 Counts are per item, so `succeededCount + failedCount + skippedCount === totalItems` even when items have multiple attempts:
 
@@ -16,7 +16,7 @@ Counts are per item, so `succeededCount + failedCount + skippedCount === totalIt
 
 Attempt-level detail remains available through [`listExperimentResults()`](https://mastra.ai/reference/datasets/listExperimentResults).
 
-Finalization is idempotent: calling it on an already-finalized experiment returns the stored record without recomputing.
+Finalization is idempotent: calling it on an already completed or failed experiment returns the stored record without recomputing.
 
 ## Usage example
 

package/.docs/reference/datasets/listExperiments.md

@@ -67,9 +67,9 @@ for (const exp of experiments) {
 
 **result.experiments.datasetVersion** (`number | null`): Dataset version used for the experiment.
 
-**result.experiments.targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Type of target used.
+**result.experiments.targetType** (`'agent' | 'workflow' | 'scorer' | 'processor' | null`): Type of target used. null for caller-driven ingestion experiments.
 
-**result.experiments.targetId** (`string`): ID of the target used.
+**result.experiments.targetId** (`string | null`): ID of the target used. null for caller-driven ingestion experiments.
 
 **result.experiments.status** (`'pending' | 'running' | 'completed' | 'failed'`): Current status of the experiment.
 

package/.docs/reference/datasets/submitExperimentResult.md

@@ -37,7 +37,7 @@ The item must be visible at the experiment's pinned dataset version. Submissions
 
 **groundTruth** (`unknown`): Expected output. Defaults to the dataset item's ground truth at the pinned version.
 
-**error** (`object`): Error details (message, optional stack and code) when the item failed.
+**error** (`object | null`): Error details (message, optional stack and code) when the item failed.
 
 **startedAt** (`Date`): When the worker started this item.
 

package/.docs/reference/editor/tools.md

@@ -78,10 +78,18 @@ Stored HTTP definitions don't accept arbitrary headers. When the reserved `mastr
 
 MCP tools can be allowlisted at two levels:
 
-1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client.
-2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent.
+1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client. Omitting `tools` at this level exposes all of the server's tools.
+2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent. Omitting `tools` at this level selects no tools.
 
-Agent-level tool names can use namespaced or bare names. An explicit empty `tools` map selects all tools. With the current resolver, omitting `tools` from an agent-level MCP reference selects none.
+Agent-level tool names can use namespaced or bare names. To select every remaining tool at the agent level, pass an explicit empty `tools` map:
+
+```typescript
+const mcpClients = {
+  'docs-client': { tools: {} }, // all tools
+  'search-client': { tools: { docs_search: {} } }, // only docs_search
+  'billing-client': {}, // no tools
+}
+```
 
 ### Namespacing
 

package/.docs/reference/evals/completeness.md

@@ -25,7 +25,7 @@ The `.run()` method returns a result in the following shape:
 ```typescript
 {
   runId: string,
-  extractStepResult: {
+  preprocessStepResult: {
     inputElements: string[],
     outputElements: string[],
     missingElements: string[],
@@ -52,9 +52,9 @@ The extraction process includes:
 - Special handling of short words (3 characters or less)
 - Deduplication of elements
 
-### `extractStepResult`
+### `preprocessStepResult`
 
-From the `.run()` method, you can get the `extractStepResult` object with the following properties:
+From the `.run()` method, you can get the `preprocessStepResult` object with the following properties:
 
 - **inputElements**: Key elements found in the input (e.g., nouns, verbs, topics, terms).
 - **outputElements**: Key elements found in the output.

package/.docs/reference/evals/context-precision.md

@@ -34,7 +34,7 @@ Either `context` or `contextExtractor` must be provided. If both are provided, `
 
 ## `.run()` returns
 
-**score** (`number`): Mean Average Precision score between 0 and scale (default 0-1)
+**score** (`number`): Mean Average Precision score between 0 and scale (default 0-1). Assumes a positive scale.
 
 **reason** (`string`): Human-readable explanation of the context precision evaluation
 

package/.docs/reference/evals/create-scorer.md

@@ -10,7 +10,7 @@ Mastra provides a unified `createScorer` factory that allows you to define custo
 
 Use the `createScorer` factory to define your scorer with a name, description, and optional judge configuration. Then chain step methods to build your evaluation pipeline. You must provide at least a `generateScore` step.
 
-**Prompt object steps** are step configurations expressed as objects with `description` + `createPrompt` (and `outputSchema` for `preprocess`/`analyze`). These steps invoke the judge LLM. **Function steps** are plain functions and never call the judge.
+**Prompt object steps** are step configurations expressed as objects with `description` + `createPrompt` (and `outputSchema` for `preprocess`/`analyze`, but not for `generateScore`). These steps invoke the judge LLM. **Function steps** are plain functions and never call the judge.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'
@@ -65,7 +65,7 @@ This function returns a scorer builder that you can chain step methods onto. See
 
 The judge only runs for steps defined as **prompt objects** (`preprocess`, `analyze`, `generateScore`, `generateReason` in prompt mode). If you use function steps only, the judge is never called and there is no LLM output to inspect. In that case, any score/reason must be produced by your functions.
 
-When a prompt-object step runs, its structured LLM output is stored in the corresponding result field (`preprocessStepResult`, `analyzeStepResult`, or the value consumed by `calculateScore` in `generateScore`).
+When a prompt-object step runs, its structured LLM output is stored in the corresponding result field (`preprocessStepResult` or `analyzeStepResult`). For `generateScore`, the judge returns `{ score: number }` and `score` becomes the scorer's score.
 
 ## Retry judge requests
 
@@ -289,15 +289,11 @@ The method must return a numerical score.
 
 **description** (`string`): Description of what this scoring step does.
 
-**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for the expected output of the generateScore step.
-
 **createPrompt** (`function`): Function: ({ run, results }) => string. Returns the prompt for the LLM.
 
 **judge** (`object`): (Optional) LLM judge for this step (can override main judge). See Judge Object section.
 
-When using prompt object mode, you must also provide a `calculateScore` function to convert the LLM output to a numerical score:
-
-**calculateScore** (`function`): Function: ({ run, results, analyzeStepResult }) => number. Converts the LLM's structured output into a numerical score.
+In prompt object mode, don't set `outputSchema`. Mastra asks the judge for structured output of the form `{ score: number }` and uses `score` as the step result.
 
 ### `generateReason`
 

package/.docs/reference/evals/faithfulness.md

@@ -12,9 +12,11 @@ The `createFaithfulnessScorer()` function accepts a single options object with t
 
 **model** (`LanguageModel`): Configuration for the model used to evaluate faithfulness.
 
-**context** (`string[]`): Array of context chunks against which the output's claims will be verified.
+**options** (`{ context?: string[]; scale?: number }`): Configuration options for the scorer.
 
-**scale** (`number`): The maximum score value. The final score will be normalized to this scale. (Default: `1`)
+**options.context** (`string[]`): Array of context chunks against which the output's claims will be verified. When omitted, the scorer uses the results of tool calls in the run output.
+
+**options.scale** (`number`): The maximum score value. The final score will be normalized to this scale.
 
 This function returns an instance of the MastraScorer class. The `.run()` method accepts the same input as other scorers (see the [MastraScorer reference](https://mastra.ai/reference/evals/mastra-scorer)), but the return value includes LLM-specific fields as documented below.
 
@@ -22,7 +24,7 @@ This function returns an instance of the MastraScorer class. The `.run()` method
 
 **runId** (`string`): The id of the run (optional).
 
-**preprocessStepResult** (`string[]`): Array of extracted claims from the output.
+**preprocessStepResult** (`object`): Object with the claims extracted from the output: { claims: string\[] }
 
 **preprocessPrompt** (`string`): The prompt sent to the LLM for the preprocess step (optional).
 
@@ -64,7 +66,7 @@ Final score: `(supported_claims / total_claims) * scale`
 
 ### Score interpretation
 
-A faithfulness score between 0 and 1:
+A faithfulness score between 0 and the configured scale (default 1). With the default scale:
 
 - **1.0**: All claims are accurate and directly supported by the context.
 - **0.7 to 0.9**: Most claims are correct, with minor additions or omissions.

package/.docs/reference/evals/filter-run.md

@@ -115,7 +115,7 @@ The `partTypes` option accepts `MastraPartType` values. Each value is prefix-mat
 ## Filtering behavior
 
 - **Part type filtering** applies to both `input.rememberedMessages` and `output` when they contain agent message arrays.
-- **Tool name filtering** only affects messages that contain tool invocations. Text-only messages pass through.
+- **Tool name filtering** only affects messages that contain tool invocations. Messages without tool invocations are filtered by `partTypes` only, and pass through when `partTypes` isn't set.
 - **System messages** (`systemMessages`, `taggedSystemMessages`) are never filtered, regardless of `partTypes` or `toolNames`.
 - **Message limits** (`maxRememberedMessages`, `maxOutputMessages`) apply after type and tool filtering, taking the most recent messages.
-- When both `partTypes` and `toolNames` are set, a message must satisfy both filters to be kept.
+- When both `partTypes` and `toolNames` are set, a message with tool invocations must satisfy both filters to be kept.

package/.docs/reference/evals/trajectory-accuracy.md

@@ -93,13 +93,14 @@ The discriminated union includes these additional step types:
 | Step type              | Key properties                                                |
 | ---------------------- | ------------------------------------------------------------- |
 | `mcp_tool_call`        | `toolArgs`, `toolResult`, `mcpServer`, `success`              |
+| `provider_tool_call`   | `toolArgs`, `toolResult`, `success`                           |
 | `model_generation`     | `modelId`, `promptTokens`, `completionTokens`, `finishReason` |
 | `agent_run`            | `agentId`                                                     |
 | `workflow_run`         | `workflowId`, `status`                                        |
 | `workflow_conditional` | `conditionCount`, `selectedSteps`                             |
 | `workflow_parallel`    | `branchCount`, `parallelSteps`                                |
 | `workflow_loop`        | `loopType`, `totalIterations`                                 |
-| `workflow_sleep`       | `durationMs`, `sleepType`                                     |
+| `workflow_sleep`       | `sleepDurationMs`, `sleepType`                                |
 | `workflow_wait_event`  | `eventName`, `eventReceived`                                  |
 | `processor_run`        | `processorId`                                                 |
 
@@ -261,7 +262,7 @@ Only checks that each expected step is present. Order is ignored, and extra step
 
 ## Code-based scoring details
 
-- **Continuous scores**: Returns values between 0.0 and 1.0 in relaxed mode; binary (0 or 1) in strict mode
+- **Continuous scores**: Returns values between 0.0 and 1.0 in every ordering mode. In strict mode, the score is the share of expected steps matched in order, minus penalties for extra steps and, when `allowRepeatedSteps` is `false`, repeated steps
 - **Deterministic**: Same input always produces the same output
 - **Fast**: No external API calls
 

package/.docs/reference/index.md

@@ -27,7 +27,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getMetadata()](https://mastra.ai/reference/agents/getMetadata)
 - [.getModel()](https://mastra.ai/reference/agents/getModel)
 - [.getSkill()](https://mastra.ai/reference/agents/getSkill)
-- [.getTools()](https://mastra.ai/reference/agents/getTools)
 - [.getVoice()](https://mastra.ai/reference/agents/getVoice)
 - [.listAgents()](https://mastra.ai/reference/agents/listAgents)
 - [.listScorers()](https://mastra.ai/reference/agents/listScorers)

package/.docs/reference/memory/listThreads.md

@@ -69,7 +69,7 @@ const result = await memory.listThreads({
 
 **page** (`number`): Page number (0-indexed) to retrieve
 
-**perPage** (`number | false`): Maximum number of threads to return per page, or false to fetch all
+**perPage** (`number | false`): Maximum number of threads to return per page, or false to fetch all (Default: `100`)
 
 **orderBy** (`{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }`): Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })
 

package/.docs/reference/migrations/mcp-v2.md

@@ -16,12 +16,12 @@ Streamable HTTP still streams responses as Server-Sent Events. What's removed is
 
 ### `@mastra/core` peer range
 
-`@mastra/mcp` 2.0 requires `@mastra/core` 1.68 or newer, which adds the shared server contract (`mcpVersion`, `MCPToolExecutionResultV2`, `context.mcp.protocolVersion`). Update both packages together.
+`@mastra/mcp` 2.0 requires `@mastra/core` 1.76 or a later 1.x release, which includes the shared server contract (`mcpVersion`, `MCPToolExecutionResultV2`, `context.mcp.protocolVersion`). Update both packages together.
 
 ```diff
 - "@mastra/core": "^1.60.0",
 - "@mastra/mcp": "^1.17.0"
-+ "@mastra/core": "^1.68.0",
++ "@mastra/core": "^1.76.0",
 + "@mastra/mcp": "^2.0.0"
 ```
 

package/.docs/reference/migrations/upgrade-to-v1/agent.md

@@ -81,7 +81,7 @@ To migrate, replace property access with the corresponding getter methods.
 - const tools = agent.tools;
 - const instructions = agent.instructions;
 + const llm = agent.getLLM();
-+ const tools = agent.getTools();
++ const tools = await agent.listTools();
 + const instructions = agent.getInstructions();
 ```
 

package/.docs/reference/migrations/vnext-to-standard-apis.md

@@ -153,7 +153,7 @@ The following options are available in the standard `.stream()` and `generate()`
   - `errorStrategy` - Determines what happens when the output doesn’t match the schema:
 
     - 'warn' - log a warning
-    - 'error' - throw an error
+    - 'strict' - throw an error
     - 'fallback' - return a fallback value you provide
 
     ```typescript

package/.docs/reference/observability/feedback.md

@@ -345,7 +345,7 @@ Use `FeedbackInput` with `mastra.observability.addFeedback()`, `recordedTrace.ad
 
 **metadata** (`Record<string, unknown>`): Additional feedback-specific metadata.
 
-**experimentId** (`string`): Experiment or eval run identifier.
+**experimentId** (`string`): Deprecated. The experiment is derived from the target trace or span. Read correlationContext.experimentId on the exported event instead.
 
 **sourceId** (`string`): ID of the source record this feedback is linked to.
 

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -66,10 +66,20 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
 
 A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
+### Where prices come from
+
+The pricing registry uses model prices from [models.dev](https://models.dev). `@mastra/observability` includes a snapshot of these prices, and each new release of the package includes recent prices. Stored cost estimates aren't recalculated when prices change.
+
+When you run `mastra dev`, Mastra also refreshes prices from models.dev in the background once a day, and when a model has no price. Cost estimates don't wait for a refresh, so the first call to a newly released model can still have no cost. In other environments, such as production, you can turn on the refresh with `MASTRA_AUTO_REFRESH_PRICING=true`.
+
+Refreshed prices are cached in `~/.cache/mastra/pricing-data.json` and reused by later processes. If a refresh fails, Mastra keeps the prices it already has.
+
+To use only the bundled snapshot, set `MASTRA_AUTO_REFRESH_PRICING=false`. Setting `MASTRA_OFFLINE=true` also turns off the refresh.
+
 ### What cost fields may be included
 
 | Field           | Description                                                                                                        |

package/.docs/reference/observability/tracing/interfaces.md

@@ -216,6 +216,9 @@ interface Span<TType extends SpanType> {
   /** Tags for categorizing traces (only present on root spans) */
   tags?: string[]
 
+  /** Spans in other traces this span is related to */
+  links?: SpanLink[]
+
   /** End the span */
   end(options?: EndSpanOptions<TType>): void
 
@@ -778,6 +781,12 @@ interface MCPServerRequestAttributes {
 
   /** Client implementation version, when the client reported one */
   clientVersion?: string
+
+  /** W3C `traceparent` the caller sent, when it parses */
+  callerTraceparent?: string
+
+  /** W3C `tracestate` the caller sent with a valid `traceparent`, capped at 512 characters */
+  callerTracestate?: string
 }
 ```
 
@@ -998,6 +1007,23 @@ interface StartSpanOptions<TType extends SpanType> {
 
   /** Options passed when using a custom sampler strategy */
   customSamplerOptions?: CustomSamplerOptions
+
+  /** Spans in other traces this span is related to. Links with invalid IDs are ignored. */
+  links?: SpanLink[]
+}
+```
+
+### `SpanLink`
+
+A reference to a span in another trace, such as the caller's span when an `MCPServer` serves a request. Unlike a parent, a link doesn't put the two spans in the same trace.
+
+```typescript
+interface SpanLink {
+  /** Trace ID of the linked span (1-32 hexadecimal characters) */
+  traceId: string
+
+  /** Span ID of the linked span (1-16 hexadecimal characters) */
+  spanId: string
 }
 ```
 

package/.docs/reference/observability/tracing/spans.md

@@ -207,6 +207,8 @@ When tracing is disabled (sampling returns false), NO-OP spans are returned:
 class NoOpSpan<TType extends SpanType> extends BaseSpan<TType>
 ```
 
+`NoOpSpan` is exported from `@mastra/observability`. It extends that package's abstract `BaseSpan` class, which implements the `Span` interface. That class is different from the `BaseSpan` interface described on this page.
+
 A span that performs no operations. All methods are no-ops:
 
 - `id` returns `'no-op'`

package/.docs/reference/processors/moderation-processor.md

@@ -48,7 +48,7 @@ const processor = new ModerationProcessor({
 
 **id** (`string`): Processor identifier set to 'moderation'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'Moderation'
 
 **processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to moderate content before sending to LLM
 

package/.docs/reference/processors/prompt-injection-detector.md

@@ -48,9 +48,9 @@ const processor = new PromptInjectionDetector({
 
 **id** (`string`): Processor identifier set to 'prompt-injection-detector'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'Prompt Injection Detector'
 
-**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect prompt injection attempts before sending to LLM
+**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes input messages to detect prompt injection attempts before sending to LLM
 
 ## Extended usage example
 

package/.docs/reference/processors/provider-history-compat.md

@@ -54,14 +54,18 @@ Registering in `errorProcessors` alone, as the example above does, covers both h
 
 `ProviderHistoryCompat` includes these built-in compatibility rules:
 
-| Rule                                        | Provider                         | Timing                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------------- | -------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `anthropic-tool-id-format`                  | Anthropic                        | Preemptive prompt rewrite   | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` in the outbound prompt, on both the call and its result. A sanitized ID that would collide with one already in the prompt gets a `_2`, `_3`, … suffix. The provider's rejection never fires, and persisted history keeps the original IDs. A reactive fallback covers providers the preemptive check doesn't recognize, such as Vertex-hosted Claude.     |
-| `cerebras-strip-reasoning-content`          | Cerebras                         | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                                                                                                                                                                                                                                                                                                |
-| `anthropic-strip-foreign-reasoning-content` | Anthropic                        | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                                                                                                                                                                                                                                                                                      |
-| `anthropic-strip-foreign-signed-reasoning`  | Anthropic-compatible             | Preemptive prompt rewrite   | Drops signed thinking from the outbound prompt when its origin turn was stamped with a different provider (for example Kimi For Coding ↔ `anthropic/claude-sonnet-4-6`), since the receiving provider can't verify another provider's signature. Turns emptied of all content by the drop are removed from the prompt. Unstamped history is left untouched.                                                                      |
-| `azure-system-reminder-transform`           | Azure OpenAI                     | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged.                                                                                                                                                                                                                                                                      |
-| `openai-orphan-item-id`                     | OpenAI, Azure OpenAI (Responses) | Reactive API error recovery | Recovers history that OpenAI rejects with `Item 'msg_…' of type 'message' was provided without its required 'reasoning' item`. Drops the Responses `itemId` from every item-bearing part of an assistant message that carries one but has no `reasoning` part, and retries. The message then replays by value instead of as an unsatisfiable `item_reference`. The repair is applied to the in-memory list for the current turn. |
+| Rule                                             | Provider                                       | Timing                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------ | ---------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strip-foreign-provider-executed-tools`          | Anthropic, OpenAI, Azure OpenAI, Google/Vertex | Preemptive prompt rewrite   | Removes provider-executed tool calls and their paired results from the outbound prompt when they came from a different provider family, since the receiving provider can't resolve another provider's tool IDs. Persisted history is left untouched.                                                                                                                                                                             |
+| `anthropic-tool-id-format`                       | Anthropic                                      | Preemptive prompt rewrite   | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` in the outbound prompt, on both the call and its result. A sanitized ID that would collide with one already in the prompt gets a `_2`, `_3`, … suffix. The provider's rejection never fires, and persisted history keeps the original IDs. A reactive fallback covers providers the preemptive check doesn't recognize, such as Vertex-hosted Claude.     |
+| `cerebras-strip-reasoning-content`               | Cerebras                                       | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                                                                                                                                                                                                                                                                                                |
+| `anthropic-strip-empty-signed-reasoning-content` | Anthropic                                      | Preemptive prompt rewrite   | Removes assistant `reasoning` parts that carry an Anthropic signature but have empty text, which legacy records can contain. Anthropic signs the exact thinking text, so the mismatched pair would be rejected.                                                                                                                                                                                                                  |
+| `anthropic-strip-foreign-reasoning-content`      | Anthropic                                      | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                                                                                                                                                                                                                                                                                      |
+| `anthropic-strip-foreign-signed-reasoning`       | Anthropic-compatible                           | Preemptive prompt rewrite   | Drops signed thinking from the outbound prompt when its origin turn was stamped with a different provider (for example Kimi For Coding ↔ `anthropic/claude-sonnet-4-6`), since the receiving provider can't verify another provider's signature. Turns emptied of all content by the drop are removed from the prompt. Unstamped history is left untouched.                                                                      |
+| `azure-system-reminder-transform`                | Azure OpenAI                                   | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged.                                                                                                                                                                                                                                                                      |
+| `openai-orphan-item-id`                          | OpenAI, Azure OpenAI (Responses)               | Reactive API error recovery | Recovers history that OpenAI rejects with `Item 'msg_…' of type 'message' was provided without its required 'reasoning' item`. Drops the Responses `itemId` from every item-bearing part of an assistant message that carries one but has no `reasoning` part, and retries. The message then replays by value instead of as an unsatisfiable `item_reference`. The repair is applied to the in-memory list for the current turn. |
+| `anthropic-orphaned-thinking-step`               | Anthropic                                      | Reactive API error recovery | Recovers history that Anthropic rejects because `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. Removes steps that contain only reasoning when more assistant content follows them, and retries. Covers history saved by older `@mastra/memory` releases ([#22798](https://github.com/mastra-ai/mastra/issues/22798)).                                                              |
+| `ensure-user-first-turn`                         | Amazon Bedrock, Google/Vertex Gemini           | Preemptive prompt rewrite   | Inserts a minimal user turn (`.`) before a leading assistant turn, because these providers reject conversations whose first non-system turn is the assistant's. This happens when an agent greets first or `lastMessages` cuts into a thread. Runs last, so it sees the prompt after other rules have dropped emptied turns.                                                                                                     |
 
 Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call. Persisted history is never changed, so the IDs and content in memory and in the Studio stay exactly as written.
 

package/.docs/reference/processors/regex-filter-processor.md

@@ -108,7 +108,7 @@ const agent = new Agent({
 
 **name** (`'Regex Filter'`): Processor display name.
 
-**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output.
+**processInput** (`(args: ProcessInputArgs) => ProcessInputResult | Promise<ProcessInputResult>`): Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output. Returns a promise when redaction reporting is pending.
 
 **processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): Checks streaming text-delta chunks against all configured rules. Skipped when phase is input.
 

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -46,11 +46,11 @@ const processor = new SystemPromptScrubber({
 
 **id** (`string`): Processor identifier set to 'system-prompt-scrubber'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name, always 'System Prompt Scrubber'
 
-**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null>`): Processes streaming output parts to detect and handle system prompts during streaming
+**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<ChunkType | null>`): Processes streaming output parts to detect and handle system prompts during streaming
 
-**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to detect and handle system prompts in non-streaming scenarios
+**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>`): Processes final output results to detect and handle system prompts in non-streaming scenarios
 
 ## Extended usage example
 

package/.docs/reference/processors/token-limiter-processor.md

@@ -28,7 +28,7 @@ const processor = new TokenLimiterProcessor({
 
 **options.limit** (`number`): Maximum number of tokens to allow in the response
 
-**options.encoding** (`TiktokenBPE`): Optional encoding to use. Defaults to o200k\_base which is used by gpt-5.1
+**options.encoding** (`unknown`): Deprecated. Accepted for backwards compatibility but ignored. Token counts are estimated with tokenx, so no encoder is needed.
 
 **options.strategy** (`'truncate' | 'abort'`): Strategy when token limit is reached: 'truncate' stops emitting chunks, 'abort' calls abort() to stop the stream
 
@@ -40,7 +40,7 @@ const processor = new TokenLimiterProcessor({
 
 **id** (`string`): Processor identifier set to 'token-limiter'
 
-**name** (`string`): Optional processor display name
+**name** (`string`): Processor display name set to 'Token Limiter'
 
 **processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Trims stored history to fit within the token limit before the agentic loop starts in 'memory-only' trim mode, prioritizing recent messages while preserving system messages and the current turn
 

package/.docs/reference/rag/graph-rag.md

@@ -83,7 +83,7 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **content** (`string`): Text content of the document chunk
 
-**metadata** (`Record<string, any>`): Additional metadata associated with the chunk
+**metadata** (`Record<string, any>`): Additional metadata associated with the chunk, when present
 
 **score** (`number`): Combined relevance score from graph traversal
 

package/.docs/reference/server/create-route.md

@@ -50,7 +50,7 @@ function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
 
 **deprecated** (`boolean`): Mark route as deprecated
 
-**onValidationError** (`(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined`): Custom validation error handler for this route. Overrides the server-level onValidationError hook. Return { status, body } to customize the response, or undefined to use the default.
+**onValidationError** (`(error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined | void`): Custom validation error handler for this route. Overrides the server-level onValidationError hook. Return { status, body } to customize the response, or return nothing (undefined) to use the default.
 
 ## Handler parameters
 

package/.docs/reference/server/elysia-adapter.md

@@ -61,7 +61,7 @@ console.log('Server running on http://localhost:3000')
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/express-adapter.md

@@ -60,7 +60,7 @@ Express requires `express.json()` middleware for JSON body parsing. Add it befor
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/fastify-adapter.md

@@ -63,7 +63,7 @@ app.listen({ port: 3000 }, (err, address) => {
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/hono-adapter.md

@@ -57,7 +57,7 @@ export default app
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 
@@ -142,7 +142,7 @@ Available context keys:
 | `mastra`                | Mastra instance                         |
 | `requestContext`        | Request context map                     |
 | `abortSignal`           | Request cancellation signal             |
-| `tools`                 | Available tools                         |
+| `registeredTools`       | Tools registered with the adapter       |
 | `taskStore`             | Task store for A2A operations           |
 | `customRouteAuthConfig` | Per-route auth overrides                |
 | `user`                  | Authenticated user (if auth configured) |

package/.docs/reference/server/koa-adapter.md

@@ -62,7 +62,7 @@ app.listen(3000, () => {
 
 **mastra** (`Mastra`): Mastra instance
 
-**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `'/api'`)
 
 **openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
 

package/.docs/reference/server/nestjs-adapter.md

@@ -89,7 +89,7 @@ By default, Mastra routes mount under `/api`. Use `prefix` to change it.
 
 **customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH. Custom routes from server.apiRoutes (registerApiRoute()) are added automatically based on their requiresAuth setting.
 
-**tools** (`Record<string, Tool>`): Registered tools for the server
+**tools** (`ToolsInput`): Additional tools to register. Accepts Mastra tools, Vercel AI SDK tools, provider-defined tools, and web search tools.
 
 **taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
 

package/.docs/reference/server/routes.md

@@ -416,7 +416,7 @@ On authenticated servers, the read routes require the `stored-workflows:read` pe
 | `PATCH`  | `/api/datasets/:datasetId/experiments/:experimentId`                   | Update an experiment's name, description or metadata                                        |
 | `DELETE` | `/api/datasets/:datasetId/experiments/:experimentId`                   | Delete an experiment that belongs to the dataset                                            |
 | `GET`    | `/api/datasets/:datasetId/experiments/:experimentId/results`           | List experiment results                                                                     |
-| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two experiments                                                                     |
+| `POST`   | `/api/datasets/:datasetId/compare`                                     | Compare two to ten experiments                                                              |
 
 ### Delete an experiment