@mastra/mcp-docs-server 1.2.4-alpha.6 → 1.2.4-alpha.9

package/.docs/docs/browser/recording.md

@@ -21,7 +21,7 @@ Recording tools are disabled by default. Enable them only for agents that need t
 
 ## Enable recording
 
-Pass `recording.outputDir` to `AgentBrowser` or `StagehandBrowser`. The browser provider adds the `browser_record` and `browser_record_caption` tools to the agent's toolset.
+Pass a `recording` object to `AgentBrowser` or `StagehandBrowser`. The only required field is `outputDir`. You can also set `maxDurationMs`, `maxWidth`, and `maxHeight` as defaults for every recording started by this browser.
 
 The following example enables recording for `AgentBrowser`:
 
@@ -33,6 +33,9 @@ export const browser = new AgentBrowser({
   headless: false,
   recording: {
     outputDir: join(process.cwd(), 'browser-recordings'),
+    maxDurationMs: 60_000,
+    maxWidth: 1280,
+    maxHeight: 720,
   },
 })
 ```
@@ -47,10 +50,15 @@ export const browser = new StagehandBrowser({
   headless: false,
   recording: {
     outputDir: join(process.cwd(), 'browser-recordings'),
+    maxDurationMs: 60_000,
+    maxWidth: 1280,
+    maxHeight: 720,
   },
 })
 ```
 
+The agent can still override these defaults per-recording by passing `maxDurationMs`, `maxWidth`, or `maxHeight` to the `browser_record` tool at start time.
+
 ## Recording tools
 
 Enabling recording adds these tools:

package/.docs/docs/evals/datasets/overview.md

@@ -148,7 +148,15 @@ const { items: matches } = await dataset.listItems({
   search: 'Hello',
 })
 
-// List items at a specific version
+// Search and pagination can be combined with a specific version
+const { items: v2Matches } = await dataset.listItems({
+  version: 2,
+  search: 'Hello',
+  page: 0,
+  perPage: 50,
+})
+
+// Version-only snapshot returns a bare DatasetItem[]
 const v2Items = await dataset.listItems({ version: 2 })
 ```
 

package/.docs/models/environment-variables.md

@@ -118,6 +118,7 @@ List of required environment variables for each model provider and gateway suppo
 | [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)                                  | `the-grid-ai/*`            | `THEGRIDAI_API_KEY`                                                                                   |
 | [Tinfoil](https://mastra.ai/models/providers/tinfoil)                                          | `tinfoil/*`                | `TINFOIL_API_KEY`                                                                                     |
 | [Together AI](https://mastra.ai/models/providers/togetherai)                                   | `togetherai/*`             | `TOGETHER_API_KEY`                                                                                    |
+| [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)                              | `trustedrouter/*`          | `TRUSTEDROUTER_API_KEY`                                                                               |
 | [Umans AI](https://mastra.ai/models/providers/umans-ai)                                        | `umans-ai/*`               | `UMANS_AI_API_KEY`                                                                                    |
 | [Umans AI Coding Plan](https://mastra.ai/models/providers/umans-ai-coding-plan)                | `umans-ai-coding-plan/*`   | `UMANS_AI_CODING_PLAN_API_KEY`                                                                        |
 | [Upstage](https://mastra.ai/models/providers/upstage)                                          | `upstage/*`                | `UPSTAGE_API_KEY`                                                                                     |

package/.docs/models/gateways/openrouter.md

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 337 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 339 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -283,6 +283,8 @@ ANTHROPIC_API_KEY=ant-...
 | `perplexity/sonar-reasoning-pro`                                |
 | `poolside/laguna-m.1`                                           |
 | `poolside/laguna-m.1:free`                                      |
+| `poolside/laguna-xs-2.1`                                        |
+| `poolside/laguna-xs-2.1:free`                                   |
 | `poolside/laguna-xs.2`                                          |
 | `poolside/laguna-xs.2:free`                                     |
 | `qwen/qwen-2.5-72b-instruct`                                    |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4500 models from 136 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4520 models from 137 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/llmgateway.md

@@ -52,7 +52,7 @@ for await (const chunk of stream) {
 | `llmgateway/claude-sonnet-4-5`                     | 200K    |       |           |       |       |       | $3         | $15         |
 | `llmgateway/claude-sonnet-4-5-20250929`            | 200K    |       |           |       |       |       | $3         | $15         |
 | `llmgateway/claude-sonnet-4-6`                     | 1.0M    |       |           |       |       |       | $3         | $15         |
-| `llmgateway/claude-sonnet-5`                       | 1.0M    |       |           |       |       |       | $3         | $15         |
+| `llmgateway/claude-sonnet-5`                       | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `llmgateway/codestral-2508`                        | 256K    |       |           |       |       |       | $0.30      | $0.90       |
 | `llmgateway/custom`                                | 128K    |       |           |       |       |       | —          | —           |
 | `llmgateway/deepseek-v3.1`                         | 128K    |       |           |       |       |       | $0.56      | $2          |

package/.docs/models/providers/novita-ai.md

@@ -89,7 +89,7 @@ for await (const chunk of stream) {
 | `novita-ai/moonshotai/kimi-k2-instruct`                       | 131K    |       |           |       |       |       | $0.57      | $2          |
 | `novita-ai/moonshotai/kimi-k2-thinking`                       | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `novita-ai/moonshotai/kimi-k2.5`                              | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `novita-ai/moonshotai/kimi-k2.6`                              | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `novita-ai/moonshotai/kimi-k2.6`                              | 262K    |       |           |       |       |       | $0.80      | $3          |
 | `novita-ai/nousresearch/hermes-2-pro-llama-3-8b`              | 8K      |       |           |       |       |       | $0.14      | $0.14       |
 | `novita-ai/openai/gpt-oss-120b`                               | 131K    |       |           |       |       |       | $0.05      | $0.25       |
 | `novita-ai/openai/gpt-oss-20b`                                | 131K    |       |           |       |       |       | $0.04      | $0.15       |
@@ -106,7 +106,7 @@ for await (const chunk of stream) {
 | `novita-ai/qwen/qwen3-4b-fp8`                                 | 128K    |       |           |       |       |       | $0.03      | $0.03       |
 | `novita-ai/qwen/qwen3-8b-fp8`                                 | 128K    |       |           |       |       |       | $0.04      | $0.14       |
 | `novita-ai/qwen/qwen3-coder-30b-a3b-instruct`                 | 160K    |       |           |       |       |       | $0.07      | $0.27       |
-| `novita-ai/qwen/qwen3-coder-480b-a35b-instruct`               | 262K    |       |           |       |       |       | $0.30      | $1          |
+| `novita-ai/qwen/qwen3-coder-480b-a35b-instruct`               | 262K    |       |           |       |       |       | $0.38      | $2          |
 | `novita-ai/qwen/qwen3-coder-next`                             | 262K    |       |           |       |       |       | $0.20      | $2          |
 | `novita-ai/qwen/qwen3-max`                                    | 262K    |       |           |       |       |       | $2         | $8          |
 | `novita-ai/qwen/qwen3-next-80b-a3b-instruct`                  | 131K    |       |           |       |       |       | $0.15      | $2          |
@@ -129,7 +129,7 @@ for await (const chunk of stream) {
 | `novita-ai/sao10K/l31-70b-euryale-v2.2`                       | 8K      |       |           |       |       |       | $1         | $1          |
 | `novita-ai/xiaomimimo/mimo-v2-flash`                          | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `novita-ai/xiaomimimo/mimo-v2-pro`                            | 1.0M    |       |           |       |       |       | $2         | $6          |
-| `novita-ai/xiaomimimo/mimo-v2.5-pro`                          | 1.0M    |       |           |       |       |       | $2         | $6          |
+| `novita-ai/xiaomimimo/mimo-v2.5-pro`                          | 1.0M    |       |           |       |       |       | $0.52      | $1          |
 | `novita-ai/zai-org/autoglm-phone-9b-multilingual`             | 66K     |       |           |       |       |       | $0.04      | $0.14       |
 | `novita-ai/zai-org/glm-4.5`                                   | 131K    |       |           |       |       |       | $0.60      | $2          |
 | `novita-ai/zai-org/glm-4.5-air`                               | 131K    |       |           |       |       |       | $0.13      | $0.85       |

package/.docs/models/providers/stepfun-ai.md

@@ -2,7 +2,7 @@
 
 # ![StepFun AI logo](https://models.dev/logos/stepfun-ai.svg)StepFun AI
 
-Access 2 StepFun AI models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
+Access 8 StepFun AI models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
 
 Learn more in the [StepFun AI documentation](https://platform.stepfun.ai/docs/en/step-plan/integrations/open-code).
 
@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "stepfun-ai/step-3.5-flash"
+  model: "stepfun-ai/step-1-32k"
 });
 
 // Generate a response
@@ -36,8 +36,14 @@ for await (const chunk of stream) {
 
 | Model                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `stepfun-ai/step-1-32k`          | 33K     |       |           |       |       |       | $2         | $10         |
+| `stepfun-ai/step-2-16k`          | 16K     |       |           |       |       |       | $5         | $16         |
 | `stepfun-ai/step-3.5-flash`      | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `stepfun-ai/step-3.5-flash-2603` | 256K    |       |           |       |       |       | $0.10      | $0.30       |
+| `stepfun-ai/step-3.7-flash`      | 256K    |       |           |       |       |       | $0.20      | $1          |
+| `stepfun-ai/step-tts-2`          | —       |       |           |       |       |       | —          | —           |
+| `stepfun-ai/stepaudio-2.5-asr`   | —       |       |           |       |       |       | —          | —           |
+| `stepfun-ai/stepaudio-2.5-tts`   | —       |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -49,7 +55,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.stepfun.ai/step_plan/v1",
-    id: "stepfun-ai/step-3.5-flash",
+    id: "stepfun-ai/step-1-32k",
     apiKey: process.env.STEPFUN_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -67,8 +73,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "stepfun-ai/step-3.5-flash-2603"
-      : "stepfun-ai/step-3.5-flash";
+      ? "stepfun-ai/stepaudio-2.5-tts"
+      : "stepfun-ai/step-1-32k";
   }
 });
 ```

package/.docs/models/providers/stepfun.md

@@ -2,7 +2,7 @@
 
 # ![StepFun logo](https://models.dev/logos/stepfun.svg)StepFun
 
-Access 5 StepFun models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
+Access 8 StepFun models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
 
 Learn more in the [StepFun documentation](https://platform.stepfun.com/docs/zh/overview/concept).
 
@@ -41,6 +41,9 @@ for await (const chunk of stream) {
 | `stepfun/step-3.5-flash`      | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `stepfun/step-3.5-flash-2603` | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `stepfun/step-3.7-flash`      | 256K    |       |           |       |       |       | $0.20      | $1          |
+| `stepfun/step-tts-2`          | —       |       |           |       |       |       | —          | —           |
+| `stepfun/stepaudio-2.5-asr`   | —       |       |           |       |       |       | —          | —           |
+| `stepfun/stepaudio-2.5-tts`   | —       |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -70,7 +73,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "stepfun/step-3.7-flash"
+      ? "stepfun/stepaudio-2.5-tts"
       : "stepfun/step-1-32k";
   }
 });

package/.docs/models/providers/togetherai.md

@@ -40,7 +40,7 @@ for await (const chunk of stream) {
 | `togetherai/google/gemma-3n-E4B-it`                   | 33K     |       |           |       |       |       | $0.06      | $0.12       |
 | `togetherai/google/gemma-4-31B-it`                    | 262K    |       |           |       |       |       | $0.39      | $0.97       |
 | `togetherai/LiquidAI/LFM2-24B-A2B`                    | 33K     |       |           |       |       |       | $0.03      | $0.12       |
-| `togetherai/meta-llama/Llama-3.3-70B-Instruct-Turbo`  | 131K    |       |           |       |       |       | $0.88      | $0.88       |
+| `togetherai/meta-llama/Llama-3.3-70B-Instruct-Turbo`  | 131K    |       |           |       |       |       | $1         | $1          |
 | `togetherai/meta-llama/Meta-Llama-3-8B-Instruct-Lite` | 8K      |       |           |       |       |       | $0.14      | $0.14       |
 | `togetherai/MiniMaxAI/MiniMax-M2.7`                   | 203K    |       |           |       |       |       | $0.30      | $1          |
 | `togetherai/MiniMaxAI/MiniMax-M3`                     | 524K    |       |           |       |       |       | $0.30      | $1          |

package/.docs/models/providers/trustedrouter.md

@@ -0,0 +1,79 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![TrustedRouter logo](https://models.dev/logos/trustedrouter.svg)TrustedRouter
+
+Access 7 TrustedRouter models through Mastra's model router. Authentication is handled automatically using the `TRUSTEDROUTER_API_KEY` environment variable.
+
+Learn more in the [TrustedRouter documentation](https://trustedrouter.com/docs).
+
+```bash
+TRUSTEDROUTER_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "trustedrouter/auto"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [TrustedRouter documentation](https://trustedrouter.com/docs) for details.
+
+## Models
+
+| Model                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `trustedrouter/auto`       | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/cheap`      | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/e2e`        | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/fast`       | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/synth`      | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/synth-code` | 1.0M    |       |           |       |       |       | —          | —           |
+| `trustedrouter/zdr`        | 1.0M    |       |           |       |       |       | —          | —           |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.trustedrouter.com/v1",
+    id: "trustedrouter/auto",
+    apiKey: process.env.TRUSTEDROUTER_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "trustedrouter/zdr"
+      : "trustedrouter/auto";
+  }
+});
+```

package/.docs/models/providers/zenmux.md

@@ -2,7 +2,7 @@
 
 # ![ZenMux logo](https://models.dev/logos/zenmux.svg)ZenMux
 
-Access 112 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
+Access 114 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
 
 Learn more in the [ZenMux documentation](https://docs.zenmux.ai).
 
@@ -49,6 +49,8 @@ for await (const chunk of stream) {
 | `zenmux/anthropic/claude-sonnet-4`            | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `zenmux/anthropic/claude-sonnet-4.5`          | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `zenmux/anthropic/claude-sonnet-4.6`          | 1.0M    |       |           |       |       |       | $3         | $15         |
+| `zenmux/anthropic/claude-sonnet-5`            | 1.0M    |       |           |       |       |       | $2         | $10         |
+| `zenmux/anthropic/claude-sonnet-5-free`       | 1.0M    |       |           |       |       |       | —          | —           |
 | `zenmux/baidu/ernie-5.0-thinking-preview`     | 128K    |       |           |       |       |       | $0.84      | $3          |
 | `zenmux/deepseek/deepseek-chat`               | 128K    |       |           |       |       |       | $0.28      | $0.42       |
 | `zenmux/deepseek/deepseek-v3.2`               | 128K    |       |           |       |       |       | $0.28      | $0.43       |

package/.docs/models/providers.md

@@ -117,6 +117,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)
 - [Tinfoil](https://mastra.ai/models/providers/tinfoil)
 - [Together AI](https://mastra.ai/models/providers/togetherai)
+- [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)
 - [Umans AI](https://mastra.ai/models/providers/umans-ai)
 - [Umans AI Coding Plan](https://mastra.ai/models/providers/umans-ai-coding-plan)
 - [Upstage](https://mastra.ai/models/providers/upstage)

package/.docs/reference/browser/agent-browser.md

@@ -46,7 +46,7 @@ then interact with elements using their refs (e.g., @e5).`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
-**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset.
+**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
 
 **excludeTools** (`BrowserToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 

package/.docs/reference/browser/stagehand-browser.md

@@ -63,7 +63,7 @@ Use stagehand_extract to get data from pages.`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
-**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset.
+**recording** (`BrowserRecordingOptions`): Alpha option for adding browser recording tools. Provide outputDir to add browser\_record and browser\_record\_caption to the toolset. You can also set maxDurationMs, maxWidth, and maxHeight as defaults for every recording.
 
 **excludeTools** (`StagehandToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
 

package/.docs/reference/core/getAgentById.md

@@ -2,22 +2,55 @@
 
 # Mastra.getAgentById()
 
-The `.getAgentById()` method is used to retrieve an agent by its ID. The method accepts a single `string` parameter for the agent's ID.
+The `.getAgentById()` method retrieves a registered agent by its `id`. It first searches registered agents by `agent.id`. If no agent matches, it falls back to [`Mastra.getAgent()`](https://mastra.ai/reference/core/getAgent) and treats the provided value as the agent registry key.
+
+Use `mastra.getAgentById(id)` to retrieve the code-defined agent. Use `await mastra.getAgentById(id, version)` to retrieve a versioned agent.
 
 ## Usage example
 
+The following example registers an agent, retrieves it by ID, and uses the returned agent.
+
 ```typescript
-mastra.getAgentById('test-agent-123')
+import { Agent } from '@mastra/core/agent'
+import { Mastra } from '@mastra/core/mastra'
+
+const supportAgent = new Agent({
+  id: 'support-agent-id',
+  name: 'Support Agent',
+  instructions: 'Answer support questions clearly and concisely.',
+  model: 'openai/gpt-5.5',
+})
+
+export const mastra = new Mastra({
+  agents: {
+    supportAgent,
+  },
+})
+
+const agent = mastra.getAgentById('support-agent-id')
+
+const response = await agent.generate('How can I reset my password?')
 ```
 
 ## Parameters
 
-**id** (`string`): The ID of the agent to retrieve. The method will first search for an agent with this ID, and if not found, will attempt to use it as a name to call getAgent().
+**id** (`string`): The ID of the agent to retrieve. Mastra first searches registered agents by \`agent.id\`. If none match, it uses this value as the agent registry key and calls \`getAgent()\`.
+
+**version** (`{ versionId: string } | { status?: 'draft' | 'published' }`): Optional version selector for retrieving a versioned agent. When provided, the method returns a promise.
+
+**version.versionId** (`string`): The ID of a specific agent version to retrieve.
+
+**version.status** (`'draft' | 'published'`): Select the latest agent version with this publication status.
 
 ## Returns
 
-**agent** (`Agent`): The agent instance with the specified ID. Throws an error if the agent is not found.
+**agent** (`TAgents[TAgentName]`): The agent instance with the specified ID when \`version\` is omitted.
+
+**agent** (`Promise<TAgents[TAgentName]>`): A promise that resolves to the versioned agent instance when \`version\` is provided.
+
+Throws a `MastraError` when no agent is found by ID or registry key.
 
 ## Related
 
+- [Mastra.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [Agents overview](https://mastra.ai/docs/agents/overview)

package/.docs/reference/datasets/list.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists all datasets with pagination.
+Lists datasets with pagination and optional filters. Filters are applied at the storage layer, so callers don't need to post-filter results.
 
 ## Usage example
 
@@ -20,6 +20,18 @@ const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage:
 for (const ds of datasets) {
   console.log(`${ds.id}: ${ds.name} (v${ds.version})`)
 }
+
+// Filter by target type and name (case-insensitive substring)
+const filtered = await mastra.datasets.list({
+  page: 0,
+  perPage: 20,
+  filters: { targetType: 'agent', name: 'qa' },
+})
+
+// Filter by any-overlap match on target IDs
+const forAgents = await mastra.datasets.list({
+  filters: { targetIds: ['agent-a', 'agent-b'] },
+})
 ```
 
 ## Parameters
@@ -28,6 +40,22 @@ for (const ds of datasets) {
 
 **perPage** (`number`): Number of datasets per page. Defaults to \`20\`.
 
+**filters** (`object`): Optional filters applied at the storage layer.
+
+**filters.organizationId** (`string`): Tenancy filter: restrict to datasets in this organization.
+
+**filters.projectId** (`string`): Tenancy filter: restrict to datasets in this project.
+
+**filters.candidateKey** (`string`): Restrict to datasets belonging to this candidate key.
+
+**filters.candidateId** (`string`): Restrict to datasets belonging to this candidate ID.
+
+**filters.targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Restrict to datasets targeting this component type.
+
+**filters.targetIds** (`string[]`): Restrict to datasets whose \`targetIds\` intersect this list (any-overlap match). Empty array is treated as no filter.
+
+**filters.name** (`string`): Case-insensitive substring match on dataset \`name\`. Empty string is treated as no filter.
+
 ## Returns
 
 **result** (`Promise<object>`): Paginated dataset list.

package/.docs/reference/datasets/listExperimentResults.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists individual item results for a specific experiment with pagination.
+Lists individual item results for a specific experiment with optional filters and pagination. Filters are applied at the storage layer.
 
 ## Usage example
 
@@ -23,6 +23,18 @@ const { results, pagination } = await dataset.listExperimentResults({
   perPage: 50,
 })
 
+// Restrict to results that still need review
+const { results: pending } = await dataset.listExperimentResults({
+  experimentId: 'exp-id',
+  status: 'needs-review',
+})
+
+// Restrict to results tied to a specific trace
+const { results: byTrace } = await dataset.listExperimentResults({
+  experimentId: 'exp-id',
+  traceId: 'trace-abc',
+})
+
 for (const result of results) {
   console.log(`Item ${result.itemId}: ${result.error ? 'FAILED' : 'OK'}`)
 }
@@ -32,6 +44,12 @@ for (const result of results) {
 
 **experimentId** (`string`): ID of the experiment to list results for.
 
+**traceId** (`string`): Restrict results to those linked to this trace ID.
+
+**status** (`'needs-review' | 'reviewed' | 'complete'`): Restrict results to this per-result review status.
+
+**filters** (`ExperimentTenancyFilters`): Multi-tenant scoping filters (\`organizationId\`, \`projectId\`). Forwarded to the storage layer.
+
 **page** (`number`): Page number. Defaults to \`0\`.
 
 **perPage** (`number`): Number of results per page. Defaults to \`20\`.

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

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists all experiments (runs) for this dataset with pagination.
+Lists experiments (runs) for this dataset with optional filters and pagination. Filters are applied at the storage layer, so results are always scoped to the current dataset.
 
 ## Usage example
 
@@ -17,8 +17,17 @@ const mastra = new Mastra({
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 
+// Basic pagination
 const { experiments, pagination } = await dataset.listExperiments({ page: 0, perPage: 10 })
 
+// Filter to a specific agent version — useful for baseline vs variant comparisons
+const { experiments: v2Runs } = await dataset.listExperiments({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  agentVersion: 'v2',
+  status: 'completed',
+})
+
 for (const exp of experiments) {
   console.log(`${exp.id}: ${exp.status} (${exp.succeededCount}/${exp.totalItems})`)
 }
@@ -26,6 +35,16 @@ for (const exp of experiments) {
 
 ## Parameters
 
+**targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Restrict results to experiments run against this target type.
+
+**targetId** (`string`): Restrict results to experiments run against this target ID.
+
+**agentVersion** (`string`): Restrict results to experiments recorded against this agent version. Useful for distinguishing baseline from variant runs.
+
+**status** (`'pending' | 'running' | 'completed' | 'failed'`): Restrict results to experiments in this status.
+
+**filters** (`ExperimentTenancyFilters`): Multi-tenant scoping filters (\`organizationId\`, \`projectId\`). Forwarded to the storage layer.
+
 **page** (`number`): Page number. Defaults to \`0\`.
 
 **perPage** (`number`): Number of experiments per page. Defaults to \`20\`.

package/.docs/reference/datasets/listItems.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists items in the dataset. When a `version` is specified, returns all items at that version. Otherwise, returns paginated items from the latest version.
+Lists items in the dataset. When only `version` is provided, returns a bare `DatasetItem[]` snapshot of every item at that version. In all other cases — no arguments, or `search` / `page` / `perPage` provided with or without `version` — returns a paginated `{ items, pagination }` shape.
 
 ## Usage example
 
@@ -23,13 +23,17 @@ const result = await dataset.listItems()
 // List with search
 const filtered = await dataset.listItems({ search: 'TypeScript', page: 0, perPage: 10 })
 
-// List all items at a specific version
+// Paginated list scoped to a specific version
+const versionedPage = await dataset.listItems({ version: 2, page: 0, perPage: 20 })
+
+// Version-only snapshot returns a bare DatasetItem[] (deprecated form —
+// prefer passing page/perPage to receive the paginated shape).
 const versionedItems = await dataset.listItems({ version: 2 })
 ```
 
 ## Parameters
 
-**version** (`number`): Dataset version to list items at. When set, returns all items at that version (no pagination).
+**version** (`number`): Dataset version to list items at. When passed on its own, returns every item at that version as a bare \`DatasetItem\[]\` snapshot. Passing \`search\` / \`page\` / \`perPage\` alongside \`version\` switches to the paginated shape.
 
 **page** (`number`): Page number for pagination. Defaults to \`0\`.
 
@@ -39,11 +43,11 @@ const versionedItems = await dataset.listItems({ version: 2 })
 
 ## Returns
 
-When `version` is specified:
+When only `version` is provided (no `search`, `page`, or `perPage`):
 
-**result** (`Promise<DatasetItem[]>`): Array of all items at the specified dataset version.
+**result** (`Promise<DatasetItem[]>`): Bare array of every item at the specified dataset version. This shape is retained for backwards compatibility and is deprecated — pass \`page\` / \`perPage\` (or \`search\`) to always receive the paginated shape below.
 
-When `version` isn't specified:
+In all other cases (no arguments, or `search` / `page` / `perPage` provided with or without `version`):
 
 **result** (`Promise<object>`): Paginated response.
 

package/.docs/reference/tools/create-tool.md

@@ -55,7 +55,13 @@ export const tool = createTool({
 
 **requestContextSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
 
-**execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
+**providerOptions** (`Record<string, Record<string, unknown>>`): Provider-specific options passed to the model when this tool is used. Keys are provider names, such as \`anthropic\` or \`openai\`, and values are provider-specific configuration objects.
+
+**inputExamples** (`Array<{ input: Record<string, unknown> }>`): Examples of valid tool inputs that supported model providers can use as input examples.
+
+**background** (`ToolBackgroundConfig`): Background task configuration for this tool. When enabled, the tool can execute in the background while the agent conversation continues.
+
+**execute** (`function`): The function that contains the tool's logic. Ordinary custom tools usually provide \`execute\`, but the type allows omission for tool definitions that are executed or adapted elsewhere. It receives two parameters: the validated input data based on inputSchema (first parameter) and an execution context object (second parameter) containing \`requestContext\`, \`abortSignal\`, and other execution metadata.
 
 **execute.input** (`z.infer<TInput>`): The validated input data based on inputSchema
 
@@ -63,8 +69,6 @@ export const tool = createTool({
 
 **execute.context.requestContext** (`RequestContext`): Request Context for accessing shared state and dependencies
 
-**execute.context.tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata
-
 **execute.context.abortSignal** (`AbortSignal`): Signal for aborting the tool execution
 
 **execute.context.agent** (`AgentToolExecutionContext`): Agent-specific context, available when the tool is executed by an agent.
@@ -75,13 +79,15 @@ export const tool = createTool({
 
 **execute.context.observe** (`ToolObserve`): Observability helpers for recording child spans and structured logs from inside a tool's execute function. Always provided — when no tracing context is active, \`span\` runs the function directly and \`log\` is a no-op.
 
-**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Signature: \`(options: ToolCallOptions) => void | PromiseLike\<void>\`.
+
+**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Signature: \`({ inputTextDelta, ...options }: { inputTextDelta: string } & ToolCallOptions) => void | PromiseLike\<void>\`.
 
-**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Signature: \`({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>\`.
 
-**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: \`({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>\`.
 
-**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You do not need to configure them for ordinary `createTool()` usage.
 
 ## Returns
 
@@ -310,8 +316,9 @@ export const weatherTool = createTool({
     },
   },
   execute: async inputData => {
-    const weather = await fetchWeather(inputData.location)
-    return { weather }
+    return {
+      weather: `Current weather for ${inputData.location}: sunny`,
+    }
   },
 })
 ```
@@ -320,7 +327,44 @@ export const weatherTool = createTool({
 
 Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
 
-### Available Hooks
+The following example demonstrates a tool with all lifecycle hooks configured:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get weather for a city',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    city: z.string(),
+    forecast: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return {
+      city,
+      forecast: 'sunny',
+    }
+  },
+  onInputStart: ({ toolCallId }) => {
+    console.log(`Tool call ${toolCallId} input started`)
+  },
+  onInputDelta: ({ inputTextDelta, toolCallId }) => {
+    console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
+  },
+  onInputAvailable: ({ input, toolCallId }) => {
+    console.log(`Tool call ${toolCallId} received city: ${input.city}`)
+  },
+  onOutput: ({ output, toolCallId, toolName }) => {
+    console.log(`Tool ${toolName} call ${toolCallId} returned forecast: ${output.forecast}`)
+  },
+})
+```
+
+### Available hooks
 
 #### `onInputStart`
 
@@ -389,7 +433,7 @@ export const tool = createTool({
 })
 ```
 
-### Hook Execution Order
+### Hook execution order
 
 For a typical streaming tool call, the hooks are invoked in this order:
 
@@ -399,19 +443,14 @@ For a typical streaming tool call, the hooks are invoked in this order:
 4. Tool's **execute** function runs
 5. **onOutput**: Tool has completed successfully
 
-### Hook Parameters
-
-All hooks receive a parameter object with these common properties:
-
-- `toolCallId` (string): Unique identifier for this specific tool call
-- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+### Hook parameters
 
-Additionally:
+Hook callbacks receive these source-backed parameter shapes:
 
-- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
-- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
-- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
-- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+- `onInputStart`: Receives `ToolCallOptions`, including fields such as `toolCallId`, `messages`, and `abortSignal`.
+- `onInputDelta`: Receives `{ inputTextDelta: string } & ToolCallOptions`.
+- `onInputAvailable`: Receives `{ input: TSchemaIn } & ToolCallOptions`, where `input` is typed from `inputSchema`.
+- `onOutput`: Receives `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`, where `output` is typed from `outputSchema`. This hook does not receive `messages`.
 
 ### Error handling
 
@@ -430,7 +469,7 @@ mcp: {
 }
 ```
 
-### `ToolAnnotations` Properties
+### `ToolAnnotations` properties
 
 **title** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.4-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`9250acd`](https://github.com/mastra-ai/mastra/commit/9250acd1357f0f1f33d0dcca16f9655084c58eca), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`c64c2a8`](https://github.com/mastra-ai/mastra/commit/c64c2a8503a50252f9ca6b8e8c54cadee31b92a2), [`06e2680`](https://github.com/mastra-ai/mastra/commit/06e26806b51d2cbd858afdc66daa2b86ff3ba64a), [`1240f05`](https://github.com/mastra-ai/mastra/commit/1240f051c8e5371f1c014448bf37b1a1b9a05e47), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748)]:
+  - @mastra/core@1.49.0-alpha.5
+
+## 1.2.4-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`6a61846`](https://github.com/mastra-ai/mastra/commit/6a61846eeda29fb714549b70f1bee2bf6b141c44)]:
+  - @mastra/core@1.49.0-alpha.4
+
 ## 1.2.4-alpha.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.4-alpha.6",
+  "version": "1.2.4-alpha.9",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.49.0-alpha.3",
-    "@mastra/mcp": "^1.13.0-alpha.1"
+    "@mastra/mcp": "^1.13.0-alpha.1",
+    "@mastra/core": "1.49.0-alpha.5"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -47,7 +47,7 @@
     "vitest": "4.1.8",
     "@internal/lint": "0.0.110",
     "@internal/types-builder": "0.0.85",
-    "@mastra/core": "1.49.0-alpha.3"
+    "@mastra/core": "1.49.0-alpha.5"
   },
   "homepage": "https://mastra.ai",
   "repository": {