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

package/.docs/models/providers/nano-gpt.md

@@ -129,7 +129,7 @@ for await (const chunk of stream) {
 | `nano-gpt/deepseek-reasoner`                                     | 64K     |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/deepseek-reasoner-cheaper`                             | 128K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/deepseek-v3-0324`                                      | 128K    |       |           |       |       |       | $0.20      | $0.77       |
-| `nano-gpt/deepseek/deepseek-latest`                              | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `nano-gpt/deepseek/deepseek-latest`                              | 1.0M    |       |           |       |       |       | $0.37      | $3          |
 | `nano-gpt/deepseek/deepseek-v3.2`                                | 163K    |       |           |       |       |       | $0.28      | $0.42       |
 | `nano-gpt/deepseek/deepseek-v3.2:thinking`                       | 163K    |       |           |       |       |       | $0.28      | $0.42       |
 | `nano-gpt/deepseek/deepseek-v4-flash`                            | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
@@ -141,8 +141,8 @@ for await (const chunk of stream) {
 | `nano-gpt/deepseek/deepseek-v4-flash-vision-exp`                 | 1.0M    |       |           |       |       |       | $0.22      | $0.66       |
 | `nano-gpt/deepseek/deepseek-v4-flash:thinking`                   | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `nano-gpt/deepseek/deepseek-v4-pro`                              | 1.0M    |       |           |       |       |       | $1         | $2          |
-| `nano-gpt/deepseek/deepseek-v4-pro-0813`                         | 1.0M    |       |           |       |       |       | $1         | $3          |
-| `nano-gpt/deepseek/deepseek-v4-pro-0813:thinking`                | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `nano-gpt/deepseek/deepseek-v4-pro-0813`                         | 1.0M    |       |           |       |       |       | $0.37      | $3          |
+| `nano-gpt/deepseek/deepseek-v4-pro-0813:thinking`                | 1.0M    |       |           |       |       |       | $0.37      | $3          |
 | `nano-gpt/deepseek/deepseek-v4-pro:thinking`                     | 1.0M    |       |           |       |       |       | $1         | $2          |
 | `nano-gpt/deepseek/deepseek-v4.1-flash`                          | 1.0M    |       |           |       |       |       | $0.13      | $0.52       |
 | `nano-gpt/deepseek/deepseek-v4.1-flash:thinking`                 | 1.0M    |       |           |       |       |       | $0.13      | $0.52       |
@@ -284,7 +284,7 @@ for await (const chunk of stream) {
 | `nano-gpt/meta-llama/llama-3.1-8b-instruct`                      | 131K    |       |           |       |       |       | $0.05      | $0.09       |
 | `nano-gpt/meta-llama/llama-3.2-3b-instruct`                      | 131K    |       |           |       |       |       | $0.03      | $0.05       |
 | `nano-gpt/meta-llama/llama-3.3-70b-instruct`                     | 131K    |       |           |       |       |       | $0.05      | $0.23       |
-| `nano-gpt/meta-llama/llama-4-maverick`                           | 1.0M    |       |           |       |       |       | $0.15      | $0.60       |
+| `nano-gpt/meta-llama/llama-4-maverick`                           | 1.0M    |       |           |       |       |       | $0.19      | $0.65       |
 | `nano-gpt/meta-llama/llama-4-scout`                              | 328K    |       |           |       |       |       | $0.09      | $0.46       |
 | `nano-gpt/meta/muse-glimmer-30b`                                 | 131K    |       |           |       |       |       | $0.35      | $2          |
 | `nano-gpt/meta/muse-spark-1.1`                                   | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -333,11 +333,11 @@ for await (const chunk of stream) {
 | `nano-gpt/moonshotai/kimi-k2-instruct-0711`                      | 128K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/moonshotai/Kimi-K2-Instruct-0905`                      | 262K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/moonshotai/kimi-k2-thinking`                           | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `nano-gpt/moonshotai/kimi-k2.5`                                  | 262K    |       |           |       |       |       | $0.30      | $2          |
-| `nano-gpt/moonshotai/kimi-k2.5:thinking`                         | 262K    |       |           |       |       |       | $0.30      | $2          |
+| `nano-gpt/moonshotai/kimi-k2.5`                                  | 262K    |       |           |       |       |       | $0.38      | $2          |
+| `nano-gpt/moonshotai/kimi-k2.5:thinking`                         | 262K    |       |           |       |       |       | $0.38      | $2          |
 | `nano-gpt/moonshotai/kimi-k2.6`                                  | 262K    |       |           |       |       |       | $0.50      | $3          |
 | `nano-gpt/moonshotai/kimi-k2.6:thinking`                         | 262K    |       |           |       |       |       | $0.50      | $3          |
-| `nano-gpt/moonshotai/kimi-k2.7-code`                             | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `nano-gpt/moonshotai/kimi-k2.7-code`                             | 262K    |       |           |       |       |       | $0.67      | $3          |
 | `nano-gpt/moonshotai/kimi-k2.7-code-highspeed`                   | 262K    |       |           |       |       |       | $2         | $8          |
 | `nano-gpt/moonshotai/kimi-k3`                                    | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `nano-gpt/moonshotai/kimi-latest`                                | 1.0M    |       |           |       |       |       | $2         | $10         |
@@ -448,10 +448,9 @@ for await (const chunk of stream) {
 | `nano-gpt/qwen/qwen3-coder-30b-a3b-instruct`                     | 128K    |       |           |       |       |       | $0.10      | $0.40       |
 | `nano-gpt/qwen/qwen3-coder-flash`                                | 128K    |       |           |       |       |       | $0.30      | $2          |
 | `nano-gpt/qwen/qwen3-coder-next`                                 | 262K    |       |           |       |       |       | $0.25      | $0.80       |
-| `nano-gpt/qwen/qwen3-coder-plus`                                 | 128K    |       |           |       |       |       | $1         | $5          |
 | `nano-gpt/qwen/qwen3-max`                                        | 256K    |       |           |       |       |       | $1         | $6          |
 | `nano-gpt/qwen/qwen3-max-2026-01-23`                             | 256K    |       |           |       |       |       | $1         | $6          |
-| `nano-gpt/qwen/qwen3-next-80b-a3b-instruct`                      | 262K    |       |           |       |       |       | $0.15      | $0.65       |
+| `nano-gpt/qwen/qwen3-next-80b-a3b-instruct`                      | 262K    |       |           |       |       |       | $0.09      | $1          |
 | `nano-gpt/qwen/qwen3-next-80b-a3b-thinking`                      | 256K    |       |           |       |       |       | $0.15      | $0.65       |
 | `nano-gpt/qwen/qwen3-vl-235b-a22b-instruct`                      | 131K    |       |           |       |       |       | $0.30      | $2          |
 | `nano-gpt/qwen/qwen3-vl-235b-a22b-thinking`                      | 131K    |       |           |       |       |       | $0.50      | $6          |
@@ -498,8 +497,8 @@ for await (const chunk of stream) {
 | `nano-gpt/qwen/qwen3.8-27b-queen`                                | 524K    |       |           |       |       |       | $0.25      | $2          |
 | `nano-gpt/qwen/qwen3.8-27b-swift`                                | 262K    |       |           |       |       |       | $0.10      | $0.60       |
 | `nano-gpt/qwen/qwen3.8-27b-synthia`                              | 262K    |       |           |       |       |       | $0.10      | $0.60       |
-| `nano-gpt/qwen/qwen3.8-27b-uncensored`                           | 1.0M    |       |           |       |       |       | $0.75      | $3          |
-| `nano-gpt/qwen/qwen3.8-27b-uncensored:thinking`                  | 1.0M    |       |           |       |       |       | $0.75      | $3          |
+| `nano-gpt/qwen/qwen3.8-27b-uncensored`                           | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `nano-gpt/qwen/qwen3.8-27b-uncensored:thinking`                  | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/qwen/qwen3.8-27b:thinking`                             | 1.0M    |       |           |       |       |       | $0.15      | $0.70       |
 | `nano-gpt/qwen/qwen3.8-flash`                                    | 992K    |       |           |       |       |       | $0.14      | $0.42       |
 | `nano-gpt/qwen/qwen3.8-max`                                      | 991K    |       |           |       |       |       | $2         | $6          |
@@ -539,8 +538,8 @@ for await (const chunk of stream) {
 | `nano-gpt/TEE/gemma-4-31b-it`                                    | 262K    |       |           |       |       |       | $0.15      | $0.46       |
 | `nano-gpt/TEE/gemma4-31b`                                        | 262K    |       |           |       |       |       | $0.40      | $1          |
 | `nano-gpt/TEE/gemma4-31b:thinking`                               | 262K    |       |           |       |       |       | $0.40      | $1          |
-| `nano-gpt/TEE/glm-5.1`                                           | 203K    |       |           |       |       |       | $2         | $5          |
-| `nano-gpt/TEE/glm-5.1-thinking`                                  | 203K    |       |           |       |       |       | $2         | $5          |
+| `nano-gpt/TEE/glm-5.1`                                           | 203K    |       |           |       |       |       | $0.70      | $3          |
+| `nano-gpt/TEE/glm-5.1-thinking`                                  | 203K    |       |           |       |       |       | $0.70      | $3          |
 | `nano-gpt/TEE/glm-5.2`                                           | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `nano-gpt/TEE/glm-5.2:thinking`                                  | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `nano-gpt/TEE/glm-5.3`                                           | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -569,6 +568,7 @@ for await (const chunk of stream) {
 | `nano-gpt/TheDrummer/Cydonia-24B-v4.3`                           | 33K     |       |           |       |       |       | $0.12      | $0.15       |
 | `nano-gpt/TheDrummer/Magidonia-24B-v4.3`                         | 33K     |       |           |       |       |       | $0.10      | $0.12       |
 | `nano-gpt/TheDrummer/Rocinante-12B-v1.1`                         | 16K     |       |           |       |       |       | $0.41      | $0.59       |
+| `nano-gpt/TheDrummer/Skyfall-31B-v4.2`                           | 16K     |       |           |       |       |       | $0.12      | $0.15       |
 | `nano-gpt/TheDrummer/skyfall-36b-v2`                             | 33K     |       |           |       |       |       | $0.55      | $0.80       |
 | `nano-gpt/TheDrummer/UnslopNemo-12B-v4.1`                        | 8K      |       |           |       |       |       | $0.49      | $0.49       |
 | `nano-gpt/thinkingmachines/inkling`                              | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -597,9 +597,9 @@ for await (const chunk of stream) {
 | `nano-gpt/x-ai/grok-4.3`                                         | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/x-ai/grok-4.5`                                         | 500K    |       |           |       |       |       | $2         | $6          |
 | `nano-gpt/x-ai/grok-4.6`                                         | 500K    |       |           |       |       |       | $2         | $6          |
-| `nano-gpt/x-ai/grok-4.7`                                         | 500K    |       |           |       |       |       | $2         | $5          |
+| `nano-gpt/x-ai/grok-4.7`                                         | 500K    |       |           |       |       |       | $2         | $6          |
 | `nano-gpt/x-ai/grok-build-0.1`                                   | 256K    |       |           |       |       |       | $1         | $2          |
-| `nano-gpt/x-ai/grok-latest`                                      | 500K    |       |           |       |       |       | $2         | $5          |
+| `nano-gpt/x-ai/grok-latest`                                      | 500K    |       |           |       |       |       | $2         | $6          |
 | `nano-gpt/xiaomi/mimo-v2.5`                                      | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `nano-gpt/xiaomi/mimo-v2.5-pro`                                  | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/xiaomi/mimo-v2.5-pro:thinking`                         | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
@@ -616,11 +616,11 @@ for await (const chunk of stream) {
 | `nano-gpt/z-ai/GLM-4.5:thinking`                                 | 128K    |       |           |       |       |       | $0.30      | $1          |
 | `nano-gpt/z-ai/glm-4.5v`                                         | 66K     |       |           |       |       |       | $0.60      | $2          |
 | `nano-gpt/z-ai/glm-4.5v:thinking`                                | 66K     |       |           |       |       |       | $0.60      | $2          |
-| `nano-gpt/z-ai/glm-4.6`                                          | 200K    |       |           |       |       |       | $0.35      | $1          |
-| `nano-gpt/z-ai/glm-4.6-original`                                 | 256K    |       |           |       |       |       | $0.35      | $1          |
+| `nano-gpt/z-ai/glm-4.6`                                          | 200K    |       |           |       |       |       | $0.50      | $2          |
+| `nano-gpt/z-ai/glm-4.6-original`                                 | 256K    |       |           |       |       |       | $0.50      | $2          |
 | `nano-gpt/z-ai/GLM-4.6-turbo`                                    | 205K    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/z-ai/GLM-4.6-turbo:thinking`                           | 205K    |       |           |       |       |       | $1         | $3          |
-| `nano-gpt/z-ai/glm-4.6:thinking`                                 | 200K    |       |           |       |       |       | $0.35      | $1          |
+| `nano-gpt/z-ai/glm-4.6:thinking`                                 | 200K    |       |           |       |       |       | $0.50      | $2          |
 | `nano-gpt/z-ai/glm-4.6v`                                         | 128K    |       |           |       |       |       | $0.30      | $0.90       |
 | `nano-gpt/z-ai/glm-4.6v-original`                                | 128K    |       |           |       |       |       | $0.60      | $0.90       |
 | `nano-gpt/z-ai/glm-4.7`                                          | 200K    |       |           |       |       |       | $0.40      | $2          |
@@ -629,13 +629,13 @@ for await (const chunk of stream) {
 | `nano-gpt/z-ai/glm-4.7-original`                                 | 200K    |       |           |       |       |       | $0.60      | $2          |
 | `nano-gpt/z-ai/glm-4.7-original:thinking`                        | 200K    |       |           |       |       |       | $0.60      | $2          |
 | `nano-gpt/z-ai/glm-4.7:thinking`                                 | 200K    |       |           |       |       |       | $0.40      | $2          |
-| `nano-gpt/z-ai/glm-5`                                            | 200K    |       |           |       |       |       | $0.50      | $3          |
-| `nano-gpt/z-ai/glm-5-original`                                   | 200K    |       |           |       |       |       | $1         | $3          |
-| `nano-gpt/z-ai/glm-5-original:thinking`                          | 200K    |       |           |       |       |       | $1         | $3          |
+| `nano-gpt/z-ai/glm-5`                                            | 200K    |       |           |       |       |       | $0.60      | $2          |
+| `nano-gpt/z-ai/glm-5-original`                                   | 200K    |       |           |       |       |       | $0.60      | $2          |
+| `nano-gpt/z-ai/glm-5-original:thinking`                          | 200K    |       |           |       |       |       | $0.60      | $2          |
 | `nano-gpt/z-ai/glm-5-turbo`                                      | 203K    |       |           |       |       |       | $1         | $4          |
-| `nano-gpt/z-ai/glm-5:thinking`                                   | 200K    |       |           |       |       |       | $0.50      | $3          |
-| `nano-gpt/z-ai/glm-5.1`                                          | 200K    |       |           |       |       |       | $0.75      | $3          |
-| `nano-gpt/z-ai/glm-5.1:thinking`                                 | 200K    |       |           |       |       |       | $0.75      | $3          |
+| `nano-gpt/z-ai/glm-5:thinking`                                   | 200K    |       |           |       |       |       | $0.60      | $2          |
+| `nano-gpt/z-ai/glm-5.1`                                          | 200K    |       |           |       |       |       | $0.70      | $3          |
+| `nano-gpt/z-ai/glm-5.1:thinking`                                 | 200K    |       |           |       |       |       | $0.70      | $3          |
 | `nano-gpt/z-ai/glm-5.2`                                          | 1.0M    |       |           |       |       |       | $0.42      | $1          |
 | `nano-gpt/z-ai/glm-5.2:thinking`                                 | 1.0M    |       |           |       |       |       | $0.42      | $1          |
 | `nano-gpt/z-ai/glm-5.3`                                          | 1.0M    |       |           |       |       |       | $0.60      | $1          |

package/.docs/reference/auth/better-auth.md

@@ -41,7 +41,7 @@ export const mastra = new Mastra({
 
 **name** (`string`): Custom name for the auth provider instance. (Default: `'better-auth'`)
 
-**authorizeUser** (`(user: BetterAuthUser, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after session verification. By default, allows all authenticated users with valid sessions.
+**authorizeUser** (`(user: BetterAuthUser, request: MastraAuthRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after session verification. By default, allows all authenticated users with valid sessions.
 
 **public** (`Array<string | RegExp | [string, Methods | Methods[]]>`): Public routes that do not require authentication. Supports exact paths, wildcards, and path params.
 

package/.docs/reference/auth/clerk.md

@@ -57,7 +57,7 @@ export const mastra = new Mastra({
 
 **name** (`string`): Custom name for the auth provider instance.
 
-**authorizeUser** (`(user: User, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users, unless organizationId or organizationSlug is set, in which case only members of that organization are allowed.
+**authorizeUser** (`(user: User, request: MastraAuthRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users, unless organizationId or organizationSlug is set, in which case only members of that organization are allowed.
 
 ## Related
 

package/.docs/reference/auth/neon.md

@@ -154,9 +154,9 @@ The `MastraRBACNeon` constructor accepts a `MastraRBACNeonOptions` object.
 
 **organizationId** (`string`): Restricts membership lookup to one Neon Auth organization.
 
-**getUserRoles** (`(user: EEUser) => Promise<string[]> | string[]`): Custom function for extracting role names. When omitted, the provider fetches organization memberships from Neon Auth.
+**getUserRoles** (`(user: NeonAuthUser) => Promise<string[]> | string[]`): Custom function for extracting role names. When omitted, the provider fetches organization memberships from Neon Auth.
 
-**cache** (`{ ttlMs?: number; maxSize?: number }`): Role lookup cache configuration. The defaults are 30,000 ms and 1,000 entries.
+**cache** (`{ ttlMs?: number; maxSize?: number }`): Role lookup cache configuration. The defaults are 60,000 ms and 1,000 entries.
 
 ### Methods
 

package/.docs/reference/datasets/compareExperiments.md

@@ -16,7 +16,7 @@ import { Mastra } from '@mastra/core'
 const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
-  experimentIds: ['exp-baseline', 'exp-new'],
+  experimentIds: ['exp-baseline', 'exp-prompt-v2', 'exp-new-model'],
   baselineId: 'exp-baseline',
 })
 
@@ -27,24 +27,29 @@ for (const item of comparison.items) {
   console.log(`  Input: ${JSON.stringify(item.input)}`)
 
   for (const [expId, result] of Object.entries(item.results)) {
-    if (result) {
-      console.log(
-        `  ${expId}: output=${JSON.stringify(result.output)}, scores=${JSON.stringify(result.scores)}`,
-      )
+    if (!result) {
+      console.log(`  ${expId}: did not run this item`)
+      continue
     }
+    console.log(
+      `  ${expId}: output=${JSON.stringify(result.output)}, scores=${JSON.stringify(result.scores)}`,
+    )
   }
 }
 ```
 
 ## Parameters
 
-**experimentIds** (`string[]`): Array of experiment IDs to compare. Must contain at least 2.
+**experimentIds** (`string[]`): Array of experiment IDs to compare. Duplicate IDs are removed before the 2-ID minimum is checked, so the list must contain at least 2 distinct IDs.
 
-**baselineId** (`string`): ID of the baseline experiment. Defaults to the first ID in experimentIds.
+**baselineId** (`string`): ID of the baseline experiment. Must be one of experimentIds. Defaults to the first ID in experimentIds.
 
 ## Returns
 
-Throws `MastraError` if fewer than 2 experiment IDs are provided.
+Throws a `MastraError` with ID `COMPARE_INVALID_INPUT` when:
+
+- `experimentIds` contains fewer than 2 distinct IDs.
+- `baselineId` isn't one of `experimentIds`. Earlier versions silently ignored an unknown `baselineId`.
 
 **result** (`Promise<object>`): Comparison results.
 
@@ -58,7 +63,11 @@ Throws `MastraError` if fewer than 2 experiment IDs are provided.
 
 **result.items.groundTruth** (`unknown | null`): Ground truth for the item.
 
-**result.items.results** (`Record<string, { output: unknown; scores: Record<string, number | null> } | null>`): Results keyed by experiment ID. Each entry contains the output and scorer results for that experiment.
+**result.items.results** (`Record<string, { output: unknown; scores: Record<string, number | null> } | null>`): Results keyed by experiment ID, with an entry for every experiment in experimentIds. Each entry contains the output and scorer results for that experiment, or null when that experiment did not run the item.
+
+## HTTP route
+
+`POST /api/datasets/:datasetId/compare` calls this method. The route accepts between 2 and 10 IDs in `experimentIds`. It also still accepts the deprecated `{ experimentIdA, experimentIdB }` body, which compares the two experiments with `experimentIdA` as the baseline.
 
 ## Related
 

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'`