@mastra/mcp-docs-server 1.2.15-alpha.11 → 1.2.15-alpha.15

package/.docs/docs/agents/agent-approval.md

@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/.docs/docs/capabilities/subagents.md

@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {

package/.docs/docs/datasets/running-experiments.md

@@ -206,6 +206,55 @@ The `experiment.run.finished` event is awaited before Mastra persists the final
 
 The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
 
+## Lifecycle hooks
+
+Use lifecycle hooks to prepare state before a target runs and clean it up afterwards. This is useful when an item can't be evaluated against an empty environment. A run might need a fixture file copied into the agent's workspace, or a sandbox provisioned before the agent can touch it.
+
+Hooks run at two levels. `beforeAll` and `afterAll` run once per experiment, and `beforeEach` and `afterEach` run once per item:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'document-agent',
+  scorers: ['accuracy'],
+  beforeAll: async ({ experimentId }) => {
+    await createWorkspace(experimentId)
+  },
+  beforeEach: async ({ item }) => {
+    await copyFixture(item.metadata?.fixture)
+  },
+  afterEach: async ({ item, result }) => {
+    await clearWorkspaceFiles(item.id)
+  },
+  afterAll: async ({ summary }) => {
+    await deleteWorkspace(summary.experimentId)
+  },
+})
+```
+
+Every hook can be async. Each one receives the `experimentId`, the `mastra` instance, and the run-level `signal`, so long-running setup can be cancelled along with the experiment. The per-item hooks also receive `item`. The teardown hooks receive the result they follow: `afterEach` receives the item's `result` including scores, and `afterAll` receives the `summary` that's about to be returned.
+
+The item passed to hooks exposes `id`, `input`, `groundTruth`, and `metadata`. Fields that control execution, such as tool mocks and scorer selection, aren't exposed, so a hook can't change how the item runs.
+
+### Hook failures
+
+Each hook has a different consequence when it throws, based on how much of the run depends on it:
+
+| Hook         | On failure                                                                       |
+| ------------ | -------------------------------------------------------------------------------- |
+| `beforeAll`  | Fails the experiment. No items run.                                              |
+| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
+| `afterEach`  | Logged. The item's recorded outcome doesn't change.                              |
+| `afterAll`   | Logged. The returned summary doesn't change.                                     |
+
+When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.
+
+When `beforeEach` fails, the target and its scorers are skipped for that item, since the item's preconditions were never met. `afterEach` is also skipped for that item, on the basis that setup which didn't finish owns its own cleanup.
+
+Teardown failures are logged rather than propagated. By the time `afterEach` runs, the target has already produced a real result, and discarding it because cleanup was untidy would lose the data the experiment was run to collect.
+
+`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an [event observer](#observe-experiment-events) fails, so teardown isn't skipped when something goes wrong. It runs at most once per experiment.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.

package/.docs/models/gateways/vercel.md

@@ -2,7 +2,7 @@
 
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 323 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 322 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -247,7 +247,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-5.1-codex`                   |
 | `openai/gpt-5.1-codex-max`               |
 | `openai/gpt-5.1-codex-mini`              |
-| `openai/gpt-5.1-instant`                 |
 | `openai/gpt-5.1-thinking`                |
 | `openai/gpt-5.2`                         |
 | `openai/gpt-5.2-codex`                   |

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 5458 models from 168 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5460 models from 168 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/alibaba.md

@@ -2,7 +2,7 @@
 
 # ![Alibaba logo](https://models.dev/logos/alibaba.svg)Alibaba
 
-Access 52 Alibaba models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
+Access 54 Alibaba models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
 
 Learn more in the [Alibaba documentation](https://www.alibabacloud.com/help/en/model-studio/models).
 
@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "alibaba/qvq-max"
+  model: "alibaba/deepseek-v4-flash-0731"
 });
 
 // Generate a response
@@ -36,6 +36,8 @@ for await (const chunk of stream) {
 
 | Model                                        | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `alibaba/deepseek-v4-flash-0731`             | 1.0M    |       |           |       |       |       | $0.20      | $0.40       |
+| `alibaba/glm-5.2`                            | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `alibaba/qvq-max`                            | 131K    |       |           |       |       |       | $1         | $5          |
 | `alibaba/qwen-flash`                         | 1.0M    |       |           |       |       |       | $0.05      | $0.40       |
 | `alibaba/qwen-max`                           | 33K     |       |           |       |       |       | $2         | $6          |
@@ -99,7 +101,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
-    id: "alibaba/qvq-max",
+    id: "alibaba/deepseek-v4-flash-0731",
     apiKey: process.env.DASHSCOPE_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -118,7 +120,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "alibaba/qwq-plus"
-      : "alibaba/qvq-max";
+      : "alibaba/deepseek-v4-flash-0731";
   }
 });
 ```

package/.docs/models/providers/cortecs.md

@@ -2,7 +2,7 @@
 
 # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
 
-Access 106 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
+Access 105 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
 
 Learn more in the [Cortecs documentation](https://cortecs.ai).
 
@@ -51,7 +51,6 @@ for await (const chunk of stream) {
 | `cortecs/cosmos3-super-reasoner`              | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `cortecs/deepseek-r1-0528`                    | 164K    |       |           |       |       |       | $0.65      | $3          |
 | `cortecs/deepseek-v3.2`                       | 164K    |       |           |       |       |       | $0.30      | $0.49       |
-| `cortecs/deepseek-v4-flash`                   | 1.0M    |       |           |       |       |       | $0.15      | $0.30       |
 | `cortecs/deepseek-v4-flash-0731`              | 1.0M    |       |           |       |       |       | $0.25      | $0.30       |
 | `cortecs/deepseek-v4-pro`                     | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `cortecs/devstral-2512`                       | 262K    |       |           |       |       |       | $0.45      | $2          |

package/.docs/models/providers/digitalocean.md

@@ -59,7 +59,7 @@ for await (const chunk of stream) {
 | `digitalocean/deepseek-4-flash`                      | 1.0M    |       |           |       |       |       | $0.08      | $0.17       |
 | `digitalocean/deepseek-r1-distill-llama-70b`         | 33K     |       |           |       |       |       | $0.99      | $0.99       |
 | `digitalocean/deepseek-v3`                           | 164K    |       |           |       |       |       | —          | —           |
-| `digitalocean/deepseek-v4-flash-0731`                | 1.0M    |       |           |       |       |       | $0.13      | $0.25       |
+| `digitalocean/deepseek-v4-flash-0731`                | 1.0M    |       |           |       |       |       | $0.08      | $0.25       |
 | `digitalocean/deepseek-v4-pro`                       | 1.0M    |       |           |       |       |       | $0.87      | $2          |
 | `digitalocean/e5-large-v2`                           | 512     |       |           |       |       |       | $0.02      | —           |
 | `digitalocean/fal-ai/elevenlabs/tts/multilingual-v2` | —       |       |           |       |       |       | —          | —           |

package/.docs/models/providers/kilo.md

@@ -40,7 +40,7 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.09      | $0.18       |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.08      | $0.25       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $2         | $8          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $3         | $14         |

package/.docs/models/providers/nebius.md

@@ -2,7 +2,7 @@
 
 # ![Nebius Token Factory logo](https://models.dev/logos/nebius.svg)Nebius Token Factory
 
-Access 33 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
+Access 34 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
 
 Learn more in the [Nebius Token Factory documentation](https://docs.tokenfactory.nebius.com/).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 
 | Model                                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ------------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `nebius/deepseek-ai/DeepSeek-V4-Flash`           | 131K    |       |           |       |       |       | $0.14      | $0.28       |
 | `nebius/deepseek-ai/DeepSeek-V4-Pro`             | 1.0M    |       |           |       |       |       | $2         | $4          |
 | `nebius/google/gemma-3-27b-it`                   | 110K    |       |           |       |       |       | $0.10      | $0.30       |
 | `nebius/meta-llama/Llama-3.3-70B-Instruct`       | 128K    |       |           |       |       |       | $0.13      | $0.40       |

package/.docs/models/providers/tinfoil.md

@@ -2,7 +2,7 @@
 
 # ![Tinfoil logo](https://models.dev/logos/tinfoil.svg)Tinfoil
 
-Access 7 Tinfoil models through Mastra's model router. Authentication is handled automatically using the `TINFOIL_API_KEY` environment variable.
+Access 8 Tinfoil models through Mastra's model router. Authentication is handled automatically using the `TINFOIL_API_KEY` environment variable.
 
 Learn more in the [Tinfoil documentation](https://docs.tinfoil.sh).
 
@@ -41,6 +41,7 @@ for await (const chunk of stream) {
 | `tinfoil/gpt-oss-120b`           | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `tinfoil/gpt-oss-safeguard-120b` | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `tinfoil/kimi-k2-6`              | 256K    |       |           |       |       |       | $2         | $5          |
+| `tinfoil/kimi-k3`                | 256K    |       |           |       |       |       | $2         | $6          |
 | `tinfoil/llama3-3-70b`           | 128K    |       |           |       |       |       | $2         | $3          |
 | `tinfoil/nomic-embed-text`       | 8K      |       |           |       |       |       | $0.05      | —           |
 

package/.docs/models/providers/zeldoc.md

@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "zeldoc/z-code"
+  model: "zeldoc/zdev"
 });
 
 // Generate a response
@@ -34,9 +34,9 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model           | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| --------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `zeldoc/z-code` | 1.0M    |       |           |       |       |       | —          | —           |
+| Model         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `zeldoc/zdev` | 1.0M    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -48,7 +48,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.zeldoc.ai/v1",
-    id: "zeldoc/z-code",
+    id: "zeldoc/zdev",
     apiKey: process.env.ZELDOC_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -66,8 +66,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zeldoc/z-code"
-      : "zeldoc/z-code";
+      ? "zeldoc/zdev"
+      : "zeldoc/zdev";
   }
 });
 ```

package/.docs/reference/agent-controller/session.md

@@ -143,12 +143,14 @@ session.abort()
 
 Return the workspace resolved for this session. This preserves session-level overrides and workspaces selected from the session scope.
 
+A workspace is optional. When neither the session nor the `AgentController` configures one, the session still runs without filesystem or sandbox access, and this returns `undefined`. Check the result before using it.
+
 ```typescript
 const workspace = session.getWorkspace()
-const skill = await workspace.skills?.get('code-review')
+const skill = await workspace?.skills?.get('code-review')
 ```
 
-Returns: `Workspace`
+Returns: `Workspace | undefined`
 
 ### Session grants
 

package/.docs/reference/client-js/agents.md

@@ -421,12 +421,13 @@ Returns `{ accepted: true, runId: string, toolCallId?: string }`.
 
 ### `declineToolCall()`
 
-Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response.
+Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response. Pass an optional `reason` to tell the model why the call was rejected. The default is `Tool call was not approved by the user`.
 
 ```typescript
 const response = await agent.declineToolCall({
   runId: 'run-123',
   toolCallId: 'tool-call-456',
+  reason: 'This file is outside the allowed directory', // optional
 })
 
 response.processDataStream({

package/.docs/reference/configuration.md

@@ -567,6 +567,25 @@ export const mastra = new Mastra({
 })
 ```
 
+### bundler.minify
+
+**Type:** `boolean`\
+**Default:** `false`
+
+Minifies the bundled output, stripping comments and whitespace and shortening local identifiers. Exported names are preserved.
+
+Off by default so build output stays readable and stack traces stay usable. Enable it when bundle size matters, such as packaging a container image for an on-prem deployment. `mastra dev` is never minified.
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  bundler: {
+    minify: true,
+  },
+})
+```
+
 ### bundler.transpilePackages
 
 **Type:** `string[]`\

package/.docs/reference/datasets/startExperiment.md

@@ -79,6 +79,14 @@ console.log(`Status: ${summary2.status}`)
 
 **unmockedToolPolicy** (`'allow' | 'deny'`): Controls undeclared agent tool calls. allow executes them live. deny fails the item with TOOL\_MOCK\_NOT\_DECLARED before execution. An item-level value overrides this experiment default. (Default: `'allow'`)
 
+**beforeAll** (`(args: ExperimentHookArgs) => void | Promise<void>`): Runs once before any item executes. Receives experimentId, mastra, and signal. A failure fails the experiment and no items run.
+
+**beforeEach** (`(args: ExperimentItemHookArgs) => void | Promise<void>`): Runs before each item executes. Also receives the item (id, input, groundTruth, metadata). A failure fails that item with EXPERIMENT\_ITEM\_BEFORE\_EACH\_FAILED and skips its target, scorers, and afterEach.
+
+**afterEach** (`(args: ExperimentItemResultHookArgs) => void | Promise<void>`): Runs after each item completes. Also receives the item's result with its scores. Skipped when beforeEach failed. A failure is logged and doesn't change the item's outcome.
+
+**afterAll** (`(args: ExperimentRunResultHookArgs) => void | Promise<void>`): Runs once after the experiment finishes, on every exit path including failure. Also receives the summary. A failure is logged and doesn't change the summary.
+
 **persistence** (`ExperimentPersistencePolicy`): Controls whether this run writes experiment records and score records. Targets and scorers still execute, and results remain available in the returned summary.
 
 **persistence.experiments** (`'default' | 'none'`): Set to none to skip experiment creation, item results, progress, and terminal status writes.

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

@@ -43,6 +43,24 @@ const filter = new RegexFilterProcessor({
 })
 ```
 
+Raise the streaming carryover window for long custom matches (e.g. a fixed-length secret or a value that only matches once its closing delimiter arrives):
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  rules: [
+    {
+      name: 'armored-key',
+      pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g,
+      replacement: '[KEY]',
+    },
+  ],
+  strategy: 'redact',
+  streamCarryoverSize: 256,
+})
+```
+
 Attach to an agent:
 
 ```typescript
@@ -80,6 +98,8 @@ const agent = new Agent({
 
 **includeRedactedValues** (`boolean`): Include the text that was redacted in each report entry. Off by default, because the values are the data the processor removes. (Default: `false`)
 
+**streamCarryoverSize** (`number`): Trailing characters the streaming redact path holds back between chunks, so a match split across a chunk boundary is redacted whole. The default covers every built-in preset with a wide margin. Raise it for custom rules whose matches stay invisible to the rule until they complete, such as a fixed-length secret or a value with a closing delimiter, when such a match can be longer than the window. (Default: `128`)
+
 ## Returns
 
 **id** (`'regex-filter'`): Processor identifier.

package/.docs/reference/processors/tool-search-processor.md

@@ -29,6 +29,8 @@ const toolSearch = new ToolSearchProcessor({
 
 **options.tools** (`Record<string, Tool>`): All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.
 
+**options.includeResolvedTools** (`boolean`): Also make the tools the agent resolved for this request (MCP tools requiring the caller's credentials, or anything returned by a dynamic tools function) searchable, and withhold them from the prompt until the agent loads them. The meta-tools are never withheld. Request-resolved tools are indexed per request, so each request searches and loads its own tool instances.
+
 **options.search** (`{ topK?: number; minScore?: number; autoLoad?: boolean }`): Configuration for the search behavior.
 
 **options.search.topK** (`number`): Maximum number of tools to return in search results.
@@ -120,7 +122,37 @@ The `phase` value describes where the filter is being applied:
 - `load`: Blocks `load_tool` from loading disallowed tools.
 - `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`, or enable `includeResolvedTools`.
+
+## Searching request-resolved tools
+
+The `tools` option is fixed at construction, so you can't list tools that only exist per request (MCP tools that need the caller's credentials, or anything returned by a dynamic `tools` function). By default those tools bypass search and occupy prompt space on every turn.
+
+Set `includeResolvedTools: true` to index them for the request and withhold them from the prompt until the agent loads them:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: staticTools,
+  includeResolvedTools: true,
+})
+
+const agent = new Agent({
+  id: 'mcp-agent',
+  name: 'mcp-agent',
+  instructions: 'Search for a tool when you need a capability you do not have.',
+  model: 'openai/gpt-5.6-sol',
+  // Resolved per request, then searchable alongside staticTools
+  tools: async ({ requestContext }) => mcpClient.getTools(requestContext.get('userToken')),
+  inputProcessors: [toolSearch],
+})
+```
+
+Each request is indexed on its own, so a tool loaded by one caller never resolves to another caller's instance of the same tool name.
+
+This option applies to every tool resolved for the request, including memory, workspace, skill, and browser tools. Only the `search_tools` and `load_tool` meta-tools stay in the prompt, so any tool the agent relies on implicitly must be found through search before it can be called.
 
 ## Extended usage example
 

package/.docs/reference/workflows/workflow.md

@@ -127,6 +127,24 @@ export const testWorkflow = createWorkflow({
 
 **options.pruneSnapshot** (`(params: { snapshot: WorkflowRunState; workflowStatus: WorkflowRunStatus }) => WorkflowRunState`): Optional hook to transform the workflow snapshot immediately before it is persisted. Must return JSON-serializable data and preserve everything the workflow needs to resume (suspended step suspendPayloads, suspendedPaths, executionPath, etc.). Used internally by agent runs to keep snapshots minimal; user workflows persist full snapshots by default.
 
+**options.onStart** (`(info: WorkflowStartCallbackInfo) => void | Promise<void>`): Callback awaited before a run starts executing, and before any step runs. Fires only on initial start, not on resume, restart, or time travel. Unlike onFinish and onError, errors thrown here are propagated: they reject the start() or stream() call and the run never executes, so this can be used as a pre-flight gate such as a quota check. The run record created by createRun() stays at status pending.
+
+**options.onStart.runId** (`string`): The workflow run ID
+
+**options.onStart.workflowId** (`string`): The workflow identifier
+
+**options.onStart.resourceId** (`string`): Resource or user identifier for multi-tenant scenarios
+
+**options.onStart.getInitData** (`() => any`): Returns the initial workflow input data
+
+**options.onStart.state** (`Record<string, any>`): The initial workflow state
+
+**options.onStart.requestContext** (`RequestContext`): The request context for the run
+
+**options.onStart.mastra** (`Mastra`): The Mastra instance, when the workflow is registered
+
+**options.onStart.logger** (`IMastraLogger`): The Mastra logger
+
 **options.onFinish** (`(result: WorkflowFinishCallbackResult) => void | Promise<void>`): Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.
 
 **options.onFinish.status** (`WorkflowRunStatus`): The workflow status: 'success', 'failed', 'suspended', or 'tripwire'

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.15-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`86b7b77`](https://github.com/mastra-ai/mastra/commit/86b7b777980d30f66e1fd134a37d2af4c22e54cc), [`80a3324`](https://github.com/mastra-ai/mastra/commit/80a33245d3110204de6f56d61211523ffe338692), [`d9d2881`](https://github.com/mastra-ai/mastra/commit/d9d2881ede6dd6c023d144215fc812062aed0890), [`82e3365`](https://github.com/mastra-ai/mastra/commit/82e3365ef7c9bf7bee2e7a7029035ea262d68895), [`1b482c2`](https://github.com/mastra-ai/mastra/commit/1b482c2d89244dd758c41e5f927a2b44041388d2), [`e6a2860`](https://github.com/mastra-ai/mastra/commit/e6a2860649cc51f87d32d78b766ae2126446ba07), [`7bd85ea`](https://github.com/mastra-ai/mastra/commit/7bd85ea7588b71c25ce9f4019c88f8539be5dcbc)]:
+  - @mastra/core@1.58.0-alpha.9
+
+## 1.2.15-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`1c75e32`](https://github.com/mastra-ai/mastra/commit/1c75e32f7fc0b9fb6f548b4407feaec8a1440212), [`c47165c`](https://github.com/mastra-ai/mastra/commit/c47165c983c87594c6952f1fd2fa51a90205034c), [`e08e789`](https://github.com/mastra-ai/mastra/commit/e08e789c1bf4cd2fe46363f7a4728536ceccc9bd), [`35cc901`](https://github.com/mastra-ai/mastra/commit/35cc90102cf834a84827acaf9eee0b6d6d1e2a3b), [`a8b4cf0`](https://github.com/mastra-ai/mastra/commit/a8b4cf02823cffebc4751a53337dfacf097c1ae1), [`f33264f`](https://github.com/mastra-ai/mastra/commit/f33264f517ae603279afd5c4251e2b40f6dd3618), [`689f2c4`](https://github.com/mastra-ai/mastra/commit/689f2c4b6c0835fe455702b01d21daa8abcd9331), [`eeae63e`](https://github.com/mastra-ai/mastra/commit/eeae63e7fbe8e1f237adc69bca6e2ac13c5ca907), [`4c186a0`](https://github.com/mastra-ai/mastra/commit/4c186a017275f45e6ed4c09de0f89550e2d09e8c), [`b0fa077`](https://github.com/mastra-ai/mastra/commit/b0fa077bcbc9b08551846fe372a0d3d15b71ed72)]:
+  - @mastra/core@1.58.0-alpha.8
+
 ## 1.2.15-alpha.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.15-alpha.11",
+  "version": "1.2.15-alpha.15",
   "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.58.0-alpha.7",
-    "@mastra/mcp": "^1.16.0-alpha.1"
+    "@mastra/mcp": "^1.16.0-alpha.1",
+    "@mastra/core": "1.58.0-alpha.9"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.121",
     "@internal/types-builder": "0.0.96",
-    "@mastra/core": "1.58.0-alpha.7"
+    "@internal/lint": "0.0.121",
+    "@mastra/core": "1.58.0-alpha.9"
   },
   "homepage": "https://mastra.ai",
   "repository": {