@mastra/mcp-docs-server 1.1.46-alpha.2 → 1.1.46-alpha.4

package/.docs/reference/agents/agent.md

@@ -426,6 +426,12 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **tools** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
 
+**hooks** (`ToolHooks`): Hooks that run before and after every tool call made by this agent. Per-execution hooks passed to \`generate()\` or \`stream()\` override matching hooks set here. See Tool hooks below.
+
+**hooks.beforeToolCall** (`(context: ToolHookContext) => void | ToolBeforeHookResult | Promise<void | ToolBeforeHookResult>`): Runs before a tool executes. Receives \`{ toolName, input, context, metadata }\`. Return \`{ proceed: false, output }\` to skip the tool call and use \`output\` as its result.
+
+**hooks.afterToolCall** (`(context: ToolAfterHookContext) => void | Promise<void>`): Runs after a tool executes. Receives \`{ toolName, input, context, metadata, output, error }\`. \`output\` is undefined when the tool throws, and \`error\` is set instead.
+
 **transform** (`ToolPayloadTransformPolicy`): Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool \`transform\` on \`createTool()\` for tool-local rules.
 
 **workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
@@ -458,6 +464,44 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Controls which fields the editor can override for this code-defined agent. Omit to allow editing instructions and tools. See Editor overrides below.
 
+## Tool hooks
+
+Use `hooks` to run logic around every tool call the agent makes, including assigned tools, memory tools, toolsets, client tools, and workspace tools.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  name: 'support-agent',
+  instructions: 'Help users with their questions.',
+  model: 'openai/gpt-5.5',
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      console.log(`Running ${toolName}`, input)
+    },
+    afterToolCall: ({ toolName, output, error }) => {
+      console.log(`Finished ${toolName}`, { output, error })
+    },
+  },
+})
+```
+
+`beforeToolCall` can short-circuit the tool call by returning `{ proceed: false, output }`. The agent skips execution and uses `output` as the tool result:
+
+```typescript
+const result = await agent.generate('Clean up old records', {
+  hooks: {
+    beforeToolCall: ({ toolName }) => {
+      if (toolName === 'deleteRecord') {
+        return { proceed: false, output: { blocked: true } }
+      }
+    },
+  },
+})
+```
+
+The hook context `metadata` includes `agentId` and `agentName`. Per-execution hooks passed to `generate()` or `stream()` override matching agent-level hooks. When a [workspace](https://mastra.ai/reference/workspace/workspace-class) also defines `tools.hooks`, workspace hooks run inside the agent hook wrapper.
+
 ## Editor overrides
 
 When you register the [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor), the `editor` field controls which parts of a code-defined agent can be changed through the editor. Fields owned by code are read-only in Studio and are stripped from saved overrides.

package/.docs/reference/agents/channels.md

@@ -247,7 +247,7 @@ The `ResolveResourceIdContext` passed to the function:
 
 ## Inline media
 
-Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that do not match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.
+Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that don't match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.
 
 The default (`['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`) matches the formats supported by major vision models. Override `inlineMedia` to expand the list (e.g. `['image/*', 'audio/*']`) or replace it entirely with a predicate function.
 

package/.docs/reference/agents/durable-agent.md

@@ -63,7 +63,7 @@ Returns: `DurableAgent`
 
 ## `createEventedAgent(options)`
 
-Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It does not accept `id` or `name` overrides.
+Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It doesn't accept `id` or `name` overrides.
 
 ```typescript
 import { createEventedAgent } from '@mastra/core/agent/durable'
@@ -151,7 +151,7 @@ await output.text
 
 Returns: `Promise<DurableAgentStreamResult>`
 
-> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, do not call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup does not fire on suspended events.
+> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
 
 ## Stream options
 

package/.docs/reference/agents/generate.md

@@ -266,6 +266,8 @@ const response = await agent.generate('Help me organize my day', {
 
 **options.clientTools** (`ToolsInput`): Client-side tools available during execution.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each generation step completes (default: false). Disabled internally when observational memory is enabled.
 
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Provider-specific options passed to the language model.

package/.docs/reference/agents/generateLegacy.md

@@ -84,6 +84,8 @@ await agent.generateLegacy('message for agent')
 
 **options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each generation step completes (default: false). Disabled internally when observational memory is enabled.
 
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is \`{ providerName: { optionKey: value } }\`. Since Mastra extends AI SDK, see the \[AI SDK documentation]\(https\://sdk.vercel.ai/docs/providers/ai-sdk-providers) for complete provider options.

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -21,7 +21,7 @@ When you pass `structuredOutput` to the underlying agent execution, the final st
 }
 ```
 
-The `object` field contains your full structured output value. Mastra emits this event for the final structured output object only. Partial structured output chunks are not exposed in the UI stream.
+The `object` field contains your full structured output value. Mastra emits this event for the final structured output object only. Partial structured output chunks aren't exposed in the UI stream.
 
 Read this event with AI SDK UI's custom data handling, such as `onData`, or render it from message data parts.
 

package/.docs/reference/ai-sdk/to-ai-sdk-stream.md

@@ -19,7 +19,7 @@ When the source agent stream includes a final structured output object, `toAISdk
 }
 ```
 
-The `object` field contains your full structured output value. This maps Mastra's final structured output chunk into the AI SDK UI stream. Partial structured output chunks are not emitted.
+The `object` field contains your full structured output value. This maps Mastra's final structured output chunk into the AI SDK UI stream. Partial structured output chunks aren't emitted.
 
 ## Usage example
 

package/.docs/reference/auth/okta.md

@@ -54,7 +54,7 @@ export const mastra = new Mastra({
 
 ### Environment variables
 
-The following environment variables are automatically used when constructor options are not provided:
+The following environment variables are automatically used when constructor options aren't provided:
 
 **OKTA\_DOMAIN** (`string`): Your Okta domain (e.g., \`dev-123456.okta.com\`). Found in your Okta admin console.
 

package/.docs/reference/auth/workos.md

@@ -81,7 +81,7 @@ const auth = new MastraAuthWorkos({
 })
 ```
 
-When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` is not the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
+When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` isn't the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
 
 ## Custom authorization
 

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

@@ -363,7 +363,7 @@ Capture a screenshot of the current page as PNG (viewport by default; set `fullP
 
 | Parameter  | Type      | Description                                                                              |
 | ---------- | --------- | ---------------------------------------------------------------------------------------- |
-| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of only the viewport (optional, default: false) |
 
 ### `browser_close`
 

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

@@ -8,6 +8,7 @@ Use `BrowserViewer` when your agent drives a browser through a CLI tool like `br
 
 ```typescript
 import { Workspace, LocalSandbox } from '@mastra/core/workspace'
+import { Memory } from '@mastra/memory'
 import { BrowserViewer } from '@mastra/browser-viewer'
 import { Agent } from '@mastra/core/agent'
 
@@ -26,6 +27,7 @@ const browserAgent = new Agent({
   model: 'openai/gpt-5.5',
   workspace,
   instructions: 'You are a web automation assistant.',
+  memory: new Memory(),
 })
 ```
 
@@ -42,7 +44,7 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 ## Constructor parameters
 
-**cli** (`'agent-browser' | 'browser-use' | 'browse-cli'`): Which CLI the agent uses for browser automation. The CLI connects to Chrome via the CDP URL.
+**cli** (`'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'`): Which CLI the agent uses for browser automation. The CLI connects to Chrome via the CDP URL.
 
 **headless** (`boolean`): Whether to run Chrome in headless mode. (Default: `true`)
 
@@ -72,7 +74,7 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 **providerType** (`'cli'`): Always 'cli'. Distinguishes BrowserViewer from SDK-based providers like AgentBrowser.
 
-**cli** (`'agent-browser' | 'browser-use' | 'browse-cli'`): The CLI provider this instance is configured for.
+**cli** (`'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'`): The CLI provider this instance is configured for.
 
 **status** (`BrowserStatus`): Current browser status: 'pending', 'launching', 'ready', 'error', 'closing', or 'closed'.
 
@@ -192,9 +194,9 @@ await viewer.injectKeyboardEvent({
 
 Each CLI must be installed separately. Each also publishes a [skill](https://mastra.ai/docs/workspace/skills) that teaches the agent its commands and workflows. When a CLI command runs through `workspace_execute_command`, Mastra detects it and injects the CDP URL automatically using the correct flag.
 
-Unlike SDK providers, `BrowserViewer` does not provide agent tools. The agent uses CLI commands through `workspace_execute_command` instead.
+Unlike SDK providers, `BrowserViewer` doesn't provide agent tools. The agent uses CLI commands through `workspace_execute_command` instead.
 
-### [agent-browser](https://www.npmjs.com/package/agent-browser)
+### [`agent-browser`](https://www.npmjs.com/package/agent-browser)
 
 Config value: `'agent-browser'` · CDP flag: `--cdp`
 
@@ -203,7 +205,7 @@ npm install -g agent-browser
 npx skills add vercel-labs/agent-browser
 ```
 
-### [browser-use](https://pypi.org/project/browser-use/)
+### [`browser-use`](https://pypi.org/project/browser-use/)
 
 Config value: `'browser-use'` · CDP flag: `--cdp-url`
 
@@ -212,13 +214,13 @@ pip install browser-use
 npx skills add browser-use/browser-use --skill browser-use
 ```
 
-### [browse-cli](https://www.npmjs.com/package/@browserbasehq/browse-cli) (command: `browse`)
+### [`browse`](https://www.npmjs.com/package/browse) (command: `browse`)
 
-Config value: `'browse-cli'` · CDP flag: `--ws`
+Config value: `'browse'` · CDP flag: `--ws`
 
 ```bash
-npm install -g @browserbasehq/browse-cli
-npx skills add browserbase/skills
+npm install -g browse
+browse skills install
 ```
 
 ## Related

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

@@ -248,7 +248,7 @@ Capture a screenshot of the current page as PNG (viewport by default; set `fullP
 
 | Parameter  | Type      | Description                                                                              |
 | ---------- | --------- | ---------------------------------------------------------------------------------------- |
-| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of only the viewport (optional, default: false) |
 
 ### `stagehand_close`
 

package/.docs/reference/cli/mastra.md

@@ -1222,7 +1222,9 @@ Prints help message and exits.
 
 By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
 
-You can opt out of the CLI analytics by setting an environment variable:
+When a server started with `mastra dev` or `mastra start` has observability metrics enabled, Mastra also sends anonymous, aggregated model usage at startup: input and output token counts per provider and model, plus the command (`dev` or `start`) and `NODE_ENV`. No prompts, responses, or other message content is ever sent. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) to check what's collected.
+
+You can opt out of all CLI and usage analytics by setting an environment variable:
 
 ```bash
 MASTRA_TELEMETRY_DISABLED=1

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

@@ -130,7 +130,7 @@ Use [`client.conversations`](https://mastra.ai/reference/client-js/conversations
 
 `response.tools` contains the configured function definitions available for the request.
 
-If the model calls a function, that activity appears in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
+If the model calls a function, that activity is included in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
 
 When `stream: true`, function calls are also emitted as Responses stream events. Read `response.function_call_arguments.delta` events for partial argument chunks and prefer `response.function_call_arguments.done` for the finalized arguments payload and tool name. Read `response.output_item.done` events for completed `function_call` and `function_call_output` items. Tool output items use `<toolCallId>:output` IDs.
 
@@ -167,7 +167,7 @@ const response = await client.responses.create({
 
 ## Provider-backed requests
 
-Use `providerOptions` when you need provider-specific options that Mastra does not normalize at the Responses layer.
+Use `providerOptions` when you need provider-specific options that Mastra doesn't normalize at the Responses layer.
 
 ```typescript
 const response = await client.responses.create({

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

@@ -243,7 +243,7 @@ await mastraClient.pauseSchedule('daily-report')
 
 ### `resumeSchedule()`
 
-Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule does not fire a backlog. Returns the updated schedule. Idempotent.
+Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule. Idempotent.
 
 ```typescript
 await mastraClient.resumeSchedule('daily-report')

package/.docs/reference/configuration.md

@@ -637,7 +637,7 @@ export const mastra = new Mastra({
 **Type:** `object`\
 **Default:** `undefined`
 
-MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state are not available.
+MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state aren't available.
 
 | Property             | Type           | Default     | Description                                          |
 | -------------------- | -------------- | ----------- | ---------------------------------------------------- |

package/.docs/reference/core/mastra-model-gateway.md

@@ -2,6 +2,8 @@
 
 Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
 
+Use `MastraModelGatewayInterface` when you want to provide a plain object gateway instead of extending the base class.
+
 ## Class overview
 
 ```typescript
@@ -17,7 +19,7 @@ class MyCustomGateway extends MastraModelGateway {
     return {
       'my-provider': {
         name: 'My Provider',
-        models: ['model-1', 'model-2'],
+        models: ['openai/gpt-5.5', 'anthropic/claude-sonnet-4-6'],
         apiKeyEnvVar: 'MY_API_KEY',
         gateway: this.id,
       },
@@ -107,6 +109,18 @@ Retrieves the API key for authentication.
 
 **Returns:** `Promise<string>`
 
+### `resolveAuth()`
+
+Resolves credentials before Mastra creates the language model. Implement this optional hook when a gateway owns authentication. If omitted, Mastra falls back to `getApiKey()`.
+
+**Parameters:**
+
+**request** (`GatewayAuthRequest`): Incoming request context containing gatewayId, providerId, modelId, and routerId for the gateway to inspect and validate.
+
+**Returns:** `GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>`
+
+A `GatewayAuthResult` may include `apiKey`, `bearerToken`, `headers`, and an optional `source` field to trace where auth came from.
+
 ### `resolveLanguageModel()`
 
 Creates a language model instance.

package/.docs/reference/core/removeWorkspace.md

@@ -0,0 +1,26 @@
+# Mastra.removeWorkspace()
+
+The `.removeWorkspace()` method removes a workspace from the Mastra runtime registry. Pass `{ destroy: true }` to destroy the workspace before it's removed.
+
+## Usage example
+
+```typescript
+await mastra.removeWorkspace('workspace-123', { destroy: true })
+```
+
+## Parameters
+
+**id** (`string`): The ID of the workspace to remove.
+
+**options** (`{ destroy?: boolean }`): Optional cleanup behavior. Set \`destroy\` to \`true\` to call \`workspace.destroy()\` before removing the workspace.
+
+## Returns
+
+**removed** (`Promise<boolean>`): \`true\` when a workspace was removed. \`false\` when no workspace exists for the ID.
+
+When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with that error and the workspace remains registered so the caller can retry cleanup.
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/editor/browser-provider.md

@@ -2,7 +2,7 @@
 
 `BrowserProvider` is the interface a package implements to register a browser with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createBrowser(config)` at agent hydration time, using the `provider` id from the stored [`StorageBrowserRef`](https://mastra.ai/reference/editor/storage-browser-ref) as the lookup key.
 
-There are no built-in browser providers. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
+No built-in browser providers are available. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
 
 ## Usage example
 

package/.docs/reference/editor/storage-browser-ref.md

@@ -2,7 +2,7 @@
 
 `StorageBrowserRef` is the inline browser configuration attached to a stored agent. The `provider` id is resolved at hydration time against the [`BrowserProvider`](https://mastra.ai/reference/editor/browser-provider) registered on [`MastraEditor.browsers`](https://mastra.ai/reference/editor/mastra-editor).
 
-It is the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -36,7 +36,7 @@ new MastraEditor({
 type StorageBrowserRef = { type: 'inline'; config: StorageBrowserConfig }
 ```
 
-There is no `{ type: 'id' }` variant for browsers — they are always inlined.
+A `{ type: 'id' }` variant for browsers isn't available — they're always inlined.
 
 ## Properties
 
@@ -70,7 +70,7 @@ The shape embedded under `config`. Defined in `@mastra/core/storage`.
 
 ## Hydration
 
-`StorageBrowserRef` is resolved lazily on `mastra.editor.agent.getById()`. The editor looks up `config.provider` on `MastraEditor.browsers` and calls `provider.createBrowser(config)`. If the provider is not registered, the editor logs a warning and returns `undefined` — the agent still loads, but without a browser.
+`StorageBrowserRef` is resolved lazily on `mastra.editor.agent.getById()`. The editor looks up `config.provider` on `MastraEditor.browsers` and calls `provider.createBrowser(config)`. If the provider isn't registered, the editor logs a warning and returns `undefined` — the agent still loads, but without a browser.
 
 ## Related
 

package/.docs/reference/editor/storage-workspace-ref.md

@@ -2,7 +2,7 @@
 
 `StorageWorkspaceRef` is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.
 
-It is the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 

package/.docs/reference/evals/rubric.md

@@ -0,0 +1,113 @@
+# Rubric scorer
+
+**Added in:** `@mastra/evals@1.3.0`
+
+The `createRubricScorer()` function creates an LLM-as-judge scorer that grades an agent's output against a rubric (a checklist of criteria). It returns a **binary** score: `1` only when every required criterion is satisfied, otherwise `0`. The `reason` lists each criterion's verdict so the agent knows exactly what to fix.
+
+This scorer is designed to drop into [`isTaskComplete`](https://mastra.ai/reference/streaming/agents/stream). Because `isTaskComplete` treats `score === 1` as "task complete" and injects the `reason` back into the conversation as feedback, the agent keeps iterating until the rubric is satisfied (or `maxSteps` is reached).
+
+## Parameters
+
+**model** (`MastraModelConfig`): The language model used to grade the output against the rubric. A smaller, cheaper model is usually sufficient for grading.
+
+**criteria** (`RubricCriterion[] | string`): The rubric to grade against. A string is treated as a newline-delimited checklist (each line becomes a required criterion). If omitted, the rubric is read at run time from a \`rubric\` value on request/additional context; if none resolves, the scorer is a no-op and returns 1.
+
+**options** (`RubricScorerOptions`): Configuration options for the scorer
+
+## `.run()` returns
+
+**score** (`number`): 1 when every required criterion is satisfied, otherwise 0 (multiplied by scale).
+
+**reason** (`string`): A per-criterion explanation listing which criteria are met or unmet and why. This is the text that isTaskComplete injects back into the conversation as feedback.
+
+## Usage with isTaskComplete
+
+Define the rubric once, attach the scorer to `isTaskComplete`, and the agent self-corrects until the rubric is satisfied:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: `You coordinate research and writing using specialized agents. Delegate to research-agent for facts, then writing-agent for content.`,
+  model: 'openai/gpt-5.5',
+  agents: { researchAgent, writingAgent },
+})
+
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: [
+    { description: 'The response includes an analysis section' },
+    { description: 'The response includes concrete recommendations' },
+  ],
+})
+
+const stream = await supervisor.stream('Research AI in education', {
+  maxSteps: 10,
+  isTaskComplete: {
+    scorers: [rubricScorer],
+    strategy: 'all',
+  },
+})
+```
+
+## String rubric
+
+A newline-delimited string is parsed into criteria, with common list markers (`-`, `*`, `1.`) stripped. Every line becomes a required criterion:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: `- All tests pass in the test suite
+- The function is named find_duplicates and accepts a single list argument`,
+})
+```
+
+## Optional criteria
+
+Mark a criterion as optional to have it graded and reported without gating completion:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: [
+    { description: 'Includes an analysis section', required: true },
+    { description: 'Includes citations', required: false },
+  ],
+})
+```
+
+## Dynamic rubric per run
+
+When no `criteria` is passed to the factory, the scorer resolves a `rubric` value from the run's request context, additional context, or input. This lets a single scorer instance grade different rubrics per run without rebuilding it:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+})
+
+await supervisor.stream('Write find_duplicates', {
+  isTaskComplete: { scorers: [rubricScorer] },
+  requestContext: {
+    rubric: '- All tests pass\n- The function is named find_duplicates',
+  },
+})
+```
+
+If no rubric resolves, the scorer returns `1` and doesn't gate the loop.
+
+## Scoring details
+
+The scorer runs in two phases:
+
+1. **Grade**: The judge model evaluates each criterion independently and returns a per-criterion verdict (`satisfied` / not) with reasoning.
+2. **Score**: The result is `1` only when every required criterion is `satisfied`, otherwise `0`. If no criteria are marked required, all criteria are treated as required.
+
+The `reason` summarizes the overall result and lists each criterion with its verdict, so a failing grade gives the agent targeted, actionable feedback rather than a generic "try again".
+
+## Related
+
+- [isTaskComplete on stream()](https://mastra.ai/reference/streaming/agents/stream)
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [createScorer](https://mastra.ai/reference/evals/create-scorer)

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

@@ -31,7 +31,7 @@ workflow_run
 
 ### Fallback extraction
 
-When storage is not available, the pipeline falls back to:
+When storage isn't available, the pipeline falls back to:
 
 - **Agents:** `extractTrajectory()` — Extracts `ToolCallStep` entries from `toolInvocations` in the agent's message output. Produces a flat list of tool calls.
 - **Workflows:** `extractWorkflowTrajectory()` — Extracts `WorkflowStepStep` entries from `stepResults`. Produces a flat list of workflow steps.
@@ -176,7 +176,7 @@ In this example, the parent workflow requires strict ordering of its steps, but
 ### Use the LLM-based scorer when:
 
 - You need **semantic understanding** of whether steps were appropriate
-- The optimal trajectory is **not predetermined** (evaluate based on task requirements)
+- The optimal trajectory **isn't predetermined** (evaluate based on task requirements)
 - You want to detect **unnecessary, redundant, or missing** steps
 - You need **explanations** for scoring decisions
 - You are evaluating **production agent behavior**
@@ -360,7 +360,7 @@ console.log(result.scores.trajectory['trajectory-accuracy'])
 
 ### Comparing step data
 
-Validates not just the step names but also step-specific data. For tool calls, this compares `toolArgs` and `toolResult`. For workflow steps, this compares `output`.
+Validates the step names and step-specific data. For tool calls, this compares `toolArgs` and `toolResult`. For workflow steps, this compares `output`.
 
 ```typescript
 const scorer = createTrajectoryAccuracyScorerCode({