@mastra/mcp-docs-server 1.2.11-alpha.6 → 1.2.12-alpha.0

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

@@ -110,7 +110,7 @@ export const responseQuality = createScorer({
 
 With this configuration, a failed request has at most three provider attempts: the initial request plus two processor retries. If `generateScore` completes and `generateReason` receives a retryable failure, only `generateReason` retries.
 
-`StreamErrorRetryProcessor` honors retryable provider metadata and narrow custom matchers. It keeps `retryUnknownErrors` disabled by default, so authentication, invalid-request, and context-length errors fail immediately unless you explicitly match them. It bounds `Retry-After` values to `30_000` milliseconds by default; use `maxRetryAfterMs` to change that cap.
+`StreamErrorRetryProcessor` honors retryable provider metadata and narrow custom matchers. It keeps `retryUnknownErrors` disabled by default, so authentication, invalid-request, and context-length errors fail immediately unless you explicitly match them. It bounds `Retry-After` values to `30_000` milliseconds by default. Use `maxRetryAfterMs` to change that cap.
 
 Avoid adding outer scorer or workflow retries. Avoid combining a nonzero model retry setting with this processor unless you intentionally accept additional attempts.
 

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

@@ -65,9 +65,9 @@ Final score: `(supported_claims / total_claims) * scale`
 A faithfulness score between 0 and 1:
 
 - **1.0**: All claims are accurate and directly supported by the context.
-- **0.7–0.9**: Most claims are correct, with minor additions or omissions.
-- **0.4–0.6**: Some claims are supported, but others are unverifiable.
-- **0.1–0.3**: Most of the content is inaccurate or unsupported.
+- **0.7 to 0.9**: Most claims are correct, with minor additions or omissions.
+- **0.4 to 0.6**: Some claims are supported, but others are unverifiable.
+- **0.1 to 0.3**: Most of the content is inaccurate or unsupported.
 - **0.0**: All claims are false or contradict the context.
 
 ## Example

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

@@ -2,7 +2,7 @@
 
 # filterRun()
 
-Creates a `prepareRun` function from declarative options. Pass the result to `createScorer()` to filter messages, limit context size, and drop unnecessary fields before the scorer pipeline runs.
+Creates a `prepareRun` function from declarative options. Pass the result to `createScorer()` to filter messages and limit context size. It also drops unnecessary fields before the scorer pipeline runs.
 
 Use [`filterRun()`](#usage-example) for declarative filtering. Write a custom `prepareRun` function directly when you need imperative logic that `filterRun()` doesn't cover. See [Custom scorers: input filtering](https://mastra.ai/docs/evals/custom-scorers) for more.
 
@@ -88,7 +88,7 @@ const simpleScorer = createScorer({
 
 **options.dropGroundTruth** (`boolean`): Remove ground truth from the run.
 
-**Returns:** `(run: ScorerRun) => ScorerRun` — A function suitable for the `prepareRun` option on [`createScorer()`](https://mastra.ai/reference/evals/create-scorer).
+**Returns:** `(run: ScorerRun) => ScorerRun`. A function suitable for the `prepareRun` option on [`createScorer()`](https://mastra.ai/reference/evals/create-scorer).
 
 ## Part types
 

package/.docs/reference/evals/hallucination.md

@@ -88,13 +88,13 @@ Final score: `(hallucinated_statements / total_statements) * scale`
 
 A hallucination score between 0 and 1:
 
-- **0.0**: No hallucination — all claims match the context.
-- **0.3–0.4**: Low hallucination — a few contradictions.
-- **0.5–0.6**: Mixed hallucination — several contradictions.
-- **0.7–0.8**: High hallucination — many contradictions.
-- **0.9–1.0**: Complete hallucination — most or all claims contradict the context.
+- **0.0**: No hallucination, all claims match the context.
+- **0.3 to 0.4**: Low hallucination, a few contradictions.
+- **0.5 to 0.6**: Mixed hallucination, several contradictions.
+- **0.7 to 0.8**: High hallucination, many contradictions.
+- **0.9 to 1.0**: Complete hallucination, most or all claims contradict the context.
 
-**Note:** The score represents the degree of hallucination - lower scores indicate better factual alignment with the provided context
+The score represents the degree of hallucination - lower scores indicate better factual alignment with the provided context
 
 ## Examples
 

package/.docs/reference/evals/keyword-coverage.md

@@ -66,11 +66,11 @@ Final score: `(matched_keywords / total_keywords) * scale`
 
 A coverage score between 0 and 1:
 
-- **1.0**: Complete coverage – all keywords present.
-- **0.7–0.9**: High coverage – most keywords included.
-- **0.4–0.6**: Partial coverage – some keywords present.
-- **0.1–0.3**: Low coverage – few keywords matched.
-- **0.0**: No coverage – no keywords found.
+- **1.0**: Complete coverage, all keywords present.
+- **0.7 to 0.9**: High coverage, most keywords included.
+- **0.4 to 0.6**: Partial coverage, some keywords present.
+- **0.1 to 0.3**: Low coverage, few keywords matched.
+- **0.0**: The response contains none of the keywords.
 
 ### Special Cases
 
@@ -80,7 +80,7 @@ The scorer handles several special cases:
 - Single word: Treated as a single keyword
 - Technical terms: Preserves compound technical terms (e.g., "React.js", "machine learning")
 - Case differences: "JavaScript" matches "javascript"
-- Common words: Ignored in scoring to focus on meaningful keywords
+- Common words: Ignored in scoring to focus on useful keywords
 
 ## Example
 

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

@@ -4,7 +4,7 @@
 
 The `MastraScorer` class is the base class for all scorers in Mastra. It provides a standard `.run()` method for evaluating input/output pairs and supports multi-step scoring workflows with preprocess → analyze → generateScore → generateReason execution flow.
 
-**Note:** Most users should use [`createScorer`](https://mastra.ai/reference/evals/create-scorer) to create scorer instances. Direct instantiation of `MastraScorer` isn't recommended.
+Most users should use [`createScorer`](https://mastra.ai/reference/evals/create-scorer) to create scorer instances. Direct instantiation of `MastraScorer` isn't recommended.
 
 ## How to get a `MastraScorer` instance
 
@@ -26,7 +26,7 @@ const scorer = createScorer({
 
 ## `.run()` method
 
-The `.run()` method is the primary way to execute your scorer and evaluate input/output pairs. It processes the data through your defined steps (preprocess → analyze → generateScore → generateReason) and returns a comprehensive result object with the score, reasoning, and intermediate results.
+The `.run()` method is the primary way to execute your scorer and evaluate input/output pairs. It processes the data through your defined steps (preprocess → analyze → generateScore → generateReason) and returns a detailed result object with the score, reasoning, and intermediate results.
 
 ```typescript
 const result = await scorer.run({
@@ -76,7 +76,8 @@ const result = await scorer.run({
 The optional `judge` record contains details about the judge model calls made by prompt-based scorer steps. Its known keys are `preprocess`, `analyze`, `generateScore`, and `generateReason`. Each key contains an ordered `executions` array.
 
 ```typescript
-interface ScorerJudgeExecution {
+interface ScorerJudgeExecutionSuccess {
+  status: 'success'
   prompt: string
   output: JSONValue
   judgeModelId: string
@@ -92,6 +93,8 @@ interface ScorerJudgeExecution {
   }
 }
 
+type ScorerJudgeExecution = ScorerJudgeExecutionSuccess
+
 interface ScorerJudgeUsage {
   inputTokens?: number
   outputTokens?: number
@@ -114,11 +117,14 @@ Use the step key to access its judge execution details:
 ```typescript
 const execution = result.judge?.generateScore?.executions[0]
 
+console.log(execution?.status)
 console.log(execution?.judgeModelId)
 console.log(execution?.usage.totalTokens)
 console.log(execution?.durationMs)
 ```
 
+The `status` value describes the outcome of the logical prompt-step execution, not the quality of the evaluated response. A structured-output fallback that eventually succeeds creates one `success` execution with an `attemptCount` greater than one.
+
 `attemptCount` counts judge invocations, including a structured-output fallback. `modelCallCount` counts the completed model steps across those attempts. `durationMs` covers the full prompt-step execution.
 
 Function steps don't create `judge` entries. Usage in this record belongs to the scorer's judge model, not the agent or workflow being evaluated. The optional `cost` field is present only when the execution directly reports an authoritative cost, source, and unit.

package/.docs/reference/evals/noise-sensitivity.md

@@ -2,9 +2,9 @@
 
 # Noise sensitivity scorer
 
-The `createNoiseSensitivityScorerLLM()` function creates a **CI/testing scorer** that evaluates how robust an agent is when exposed to irrelevant, distracting, or misleading information. Unlike live scorers that evaluate single production runs, this scorer requires predetermined test data including both baseline responses and noisy variations.
+The `createNoiseSensitivityScorerLLM()` function creates a **CI/testing scorer** that evaluates how reliable an agent is when exposed to irrelevant, distracting, or misleading information. Unlike live scorers that evaluate single production runs, this scorer requires predetermined test data including both baseline responses and noisy variations.
 
-**Important:** This isn't a live scorer. It requires pre-computed baseline responses and can't be used for real-time agent evaluation. Use this scorer in your CI/CD pipeline or testing suites only.
+This isn't a live scorer. It requires pre-computed baseline responses and can't be used for real-time agent evaluation. Use this scorer in your CI/CD pipeline or testing suites only.
 
 Before using the noise sensitivity scorer, prepare your test data:
 
@@ -177,7 +177,7 @@ Include in your test harness to:
 
 - Benchmark different models' noise resistance before deployment
 - Identify agents vulnerable to manipulation during development
-- Create comprehensive test coverage for various noise types
+- Create detailed test coverage for various noise types
 - Ensure consistent behavior across updates
 
 ### Security Testing
@@ -194,7 +194,7 @@ Evaluate resistance in controlled environments:
 - **1.0**: Perfect robustness - no impact detected
 - **0.8-0.9**: Excellent - minimal impact, core functionality preserved
 - **0.6-0.7**: Good - some impact but acceptable for most use cases
-- **0.4-0.5**: Concerning - significant vulnerabilities detected
+- **0.4-0.5**: Concerning - substantial vulnerabilities detected
 - **0.0-0.3**: Critical - agent severely compromised by noise
 
 ### Dimension analysis
@@ -472,7 +472,7 @@ const strictScorer = createNoiseSensitivityScorerLLM({
 
 ## CI test suite: Testing different noise types
 
-Create comprehensive test suites to evaluate agent performance across various noise categories in your CI pipeline:
+Create detailed test suites to evaluate agent performance across noise categories in your CI pipeline:
 
 ```typescript
 import { createNoiseSensitivityScorerLLM } from '@mastra/evals'

package/.docs/reference/evals/prompt-alignment.md

@@ -2,7 +2,7 @@
 
 # Prompt alignment scorer
 
-The `createPromptAlignmentScorerLLM()` function creates a scorer that evaluates how well agent responses align with user prompts across multiple dimensions: intent understanding, requirement fulfillment, response completeness, and format appropriateness.
+The `createPromptAlignmentScorerLLM()` function creates a scorer that evaluates how well agent responses align with user prompts across intent understanding and requirement fulfillment, plus response completeness, and format appropriateness.
 
 ## Parameters
 
@@ -80,7 +80,7 @@ Evaluates alignment with user prompts only:
 
 1. **Intent Alignment** (40% weight): Whether the response addresses the user's core request
 2. **Requirements Fulfillment** (30% weight): If all user requirements are met
-3. **Completeness** (20% weight): Whether the response is comprehensive for user needs
+3. **Completeness** (20% weight): Whether the response is detailed for user needs
 4. **Response Appropriateness** (10% weight): If format and tone match user expectations
 
 #### System Mode ('system')
@@ -139,7 +139,7 @@ Final Score = Weighted Score × scale
 - **0.8-0.9** = Very good alignment with minor gaps
 - **0.7-0.8** = Good alignment but missing some requirements or completeness
 - **0.6-0.7** = Moderate alignment with noticeable gaps
-- **0.4-0.6** = Poor alignment with significant issues
+- **0.4-0.6** = Poor alignment with substantial issues
 - **0.0-0.4** = Very poor alignment, response doesn't address the prompt effectively
 
 ### When to Use Each Mode
@@ -160,7 +160,7 @@ Final Score = Weighted Score × scale
 
 **Both Mode (`'both'`)** - Use when (default, recommended):
 
-- Comprehensive evaluation of overall AI agent performance
+- Comprehensive evaluation of AI agent performance
 - Balancing user satisfaction with system compliance
 - Production monitoring where both user and system requirements matter
 - Holistic assessment of prompt-response alignment
@@ -403,7 +403,7 @@ console.log(result)
 
 ### Excellent alignment output
 
-The output receives a high score because it perfectly addresses the intent, fulfills all requirements, and uses appropriate format.
+The output receives a high score because it perfectly addresses the intent and fulfills all requirements. It also uses the appropriate format.
 
 ```typescript
 {

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

@@ -106,7 +106,7 @@ 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".
+The `reason` summarizes the result and lists each criterion with its verdict, so a failing grade gives the agent targeted, useful feedback rather than a generic "try again".
 
 ## Related
 

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

@@ -371,9 +371,9 @@ const result = await runEvals({
 // result.verdict: 'passed' | 'scored' | 'failed'
 ```
 
-Each turn runs `agent.generate()` with the same `threadId`, so the agent sees the full conversation history. `runEvals` also injects a `resourceId` (Mastra memory scopes messages by resource + thread), defaulting it to the generated thread; pass `targetOptions.memory.resource` to pin a specific one. Cross-turn recall requires the agent to have a memory store configured; otherwise turns run in isolation. Mix single-turn (`input`) and multi-turn (`inputs`) items in the same `data` array. When using `inputs`, `input` can be omitted.
+Each turn runs `agent.generate()` with the same `threadId`, so the agent sees the full conversation history. `runEvals` also injects a `resourceId` (Mastra memory scopes messages by resource + thread), defaulting it to the generated thread. Pass `targetOptions.memory.resource` to pin a specific one. Cross-turn recall requires the agent to have a memory store configured. Otherwise turns run in isolation. Mix single-turn (`input`) and multi-turn (`inputs`) items in the same `data` array. When using `inputs`, `input` can be omitted.
 
-Scoring uses the accumulated output from all turns as `run.output`, but only the first turn as `run.input`. Prefer output-based scorers (`checks.includes`, `checks.calledTool`, `checks.similarity`) for multi-turn; input-relative scorers (e.g. faithfulness) only see the first turn's input. Trajectory scorers that read from the trace (`AgentScorerConfig.trajectory`) resolve against the last turn's span; tool-call checks that read `run.output` (like `checks.calledTool`) still see every turn.
+Scoring uses the accumulated output from all turns as `run.output`, but only the first turn as `run.input`. Prefer output-based scorers (`checks.includes`, `checks.calledTool`, `checks.similarity`) for multi-turn. Input-relative scorers (e.g. faithfulness) only see the first turn's input. Trajectory scorers that read from the trace (`AgentScorerConfig.trajectory`) resolve against the last turn's span. Tool-call checks that read `run.output` (like `checks.calledTool`) still see every turn.
 
 ### Per-turn assertions
 
@@ -403,7 +403,7 @@ result.verdict // folds in per-turn gate/threshold outcomes
 result.turnResults // [{ index, gateResults, thresholdResults, scores }]
 ```
 
-Per-turn gates/scorers evaluate only that turn (`run.input`/`run.output` are that turn's). A failing turn gate makes the verdict `failed`; a missed turn threshold (gates passing) makes it `scored`. Top-level `scorers`/`gates` still score the accumulated conversation holistically. `turns` is Agent-only and cannot be combined with `input` or `inputs`.
+Per-turn gates/scorers evaluate only that turn (`run.input`/`run.output` are that turn's). A failing turn gate makes the verdict `failed`. A missed turn threshold (gates passing) makes it `scored`. Top-level `scorers`/`gates` still score the accumulated conversation as a whole. `turns` is Agent-only and can't be combined with `input` or `inputs`.
 
 ## Related
 

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

@@ -284,7 +284,7 @@ const result = await myScorer.run({
 
 ### `extractTrajectory`
 
-Extracts a `Trajectory` from agent output messages (`MastraDBMessage[]`). Converts tool invocations into `ToolCallStep` objects. The `runEvals` pipeline calls this automatically for trajectory scorers — you only need it for direct testing.
+Extracts a `Trajectory` from agent output messages (`MastraDBMessage[]`). Converts tool invocations into `ToolCallStep` objects. The `runEvals` pipeline calls this automatically for trajectory scorers: you only need it for direct testing.
 
 Available from `@mastra/core/evals`.
 
@@ -296,7 +296,7 @@ const trajectory = extractTrajectory(agentOutputMessages)
 // trajectory.rawOutput — the original MastraDBMessage[] array
 ```
 
-**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawOutput`.
+**Returns:** `Trajectory`: Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawOutput`.
 
 ### `extractWorkflowTrajectory`
 
@@ -314,7 +314,7 @@ const trajectory = extractWorkflowTrajectory(
 // trajectory.steps — WorkflowStepStep[] in execution order
 ```
 
-**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawWorkflowResult`.
+**Returns:** `Trajectory`: Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawWorkflowResult`.
 
 ### `extractTrajectoryFromTrace`
 
@@ -363,7 +363,7 @@ Spans with types `GENERIC`, `MODEL_STEP`, `MODEL_CHUNK`, and `WORKFLOW_CONDITION
 
 Compares an actual trajectory against an expected trajectory and returns a detailed comparison result. Used internally by `createTrajectoryAccuracyScorerCode`.
 
-The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{ steps: ExpectedStep[] }`. When using `ExpectedStep[]`, you can match by name only, name + stepType, or include data for comparison. See [Expected steps](https://mastra.ai/reference/evals/trajectory-accuracy) for details.
+The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{ steps: ExpectedStep[] }`. When using `ExpectedStep[]`, you can match by name only or by name + stepType. You can also include data for comparison. See [Expected steps](https://mastra.ai/reference/evals/trajectory-accuracy) for details.
 
 ```typescript
 import { compareTrajectories } from '@mastra/evals/scorers/utils'

package/.docs/reference/evals/textual-difference.md

@@ -62,10 +62,10 @@ Final score: `(similarity_ratio * confidence) * scale`
 
 A textual difference score between 0 and 1:
 
-- **1.0**: Identical texts – no differences detected.
-- **0.7–0.9**: Minor differences – few changes needed.
-- **0.4–0.6**: Moderate differences – noticeable changes required.
-- **0.1–0.3**: Major differences – extensive changes needed.
+- **1.0**: The texts are identical.
+- **0.7 to 0.9**: Minor differences, few changes needed.
+- **0.4 to 0.6**: Moderate differences, noticeable changes required.
+- **0.1 to 0.3**: Major differences, extensive changes needed.
 - **0.0**: Completely different texts.
 
 ## Example

package/.docs/reference/evals/tool-call-accuracy.md

@@ -275,7 +275,7 @@ console.log(result.score) // 1 - auth-tool comes before fetch-tool
 
 ## LLM-based tool call accuracy scorer
 
-The `createToolCallAccuracyScorerLLM()` function from `@mastra/evals/scorers/prebuilt` uses an LLM to evaluate whether the tools called by an agent are appropriate for the given user request, providing semantic evaluation rather than exact matching.
+The `createToolCallAccuracyScorerLLM()` function from `@mastra/evals/scorers/prebuilt` uses an LLM to evaluate whether the tools called by an agent are appropriate for the user request, providing semantic evaluation rather than exact matching.
 
 ### Parameters
 

package/.docs/reference/evals/toxicity.md

@@ -2,7 +2,7 @@
 
 # Toxicity scorer
 
-The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for various forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
+The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
 
 ## Parameters
 
@@ -74,9 +74,9 @@ Final score: `(toxicity_weighted_sum / max_toxicity) * scale`
 
 A toxicity score between 0 and 1:
 
-- **0.8–1.0**: Severe toxicity.
-- **0.4–0.7**: Moderate toxicity.
-- **0.1–0.3**: Mild toxicity.
+- **0.8 to 1.0**: Severe toxicity.
+- **0.4 to 0.7**: Moderate toxicity.
+- **0.1 to 0.3**: Mild toxicity.
 - **0.0**: No toxic elements detected.
 
 ## Example

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

@@ -15,7 +15,7 @@ The `runEvals` pipeline uses two extraction strategies, depending on whether obs
 
 ### Trace-based extraction (preferred)
 
-When the target's `Mastra` instance has storage configured, the pipeline fetches the full execution trace from the observability store and calls `extractTrajectoryFromTrace()`. This produces a hierarchical trajectory with nested `children`, capturing the complete execution tree — including nested agent runs, tool calls within workflow steps, and model generations.
+When the target's `Mastra` instance has storage configured, the pipeline fetches the full execution trace from the observability store and calls `extractTrajectoryFromTrace()`. This produces a hierarchical trajectory with nested `children` that captures the complete execution tree. The tree includes nested agent runs and tool calls within workflow steps. It also includes model generations.
 
 For example, a workflow that calls an agent, which in turn calls tools, produces:
 
@@ -35,8 +35,8 @@ workflow_run
 
 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.
+- **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.
 
 These fallbacks don't capture nested execution or non-tool-call spans.
 
@@ -105,7 +105,7 @@ All step types share the base properties `name`, `durationMs`, `metadata`, and `
 
 ## Expected steps
 
-When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep` — when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
+When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep`: when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
 
 Omit `stepType` entirely to match any step by name only.
 
@@ -199,8 +199,8 @@ This function returns an instance of the MastraScorer class. See the [MastraScor
 
 The code-based scorer resolves `expectedTrajectory` from two sources, in order of priority:
 
-1. **Constructor option** — A static trajectory passed when creating the scorer. Used for all dataset items.
-2. **Dataset item** — An `expectedTrajectory` field on the dataset item, passed through the `runEvals` pipeline. Allows different expected trajectories per item.
+1. **Constructor option**: A static trajectory passed when creating the scorer. Used for all dataset items.
+2. **Dataset item**: An `expectedTrajectory` field on the dataset item, passed through the `runEvals` pipeline. Allows different expected trajectories per item.
 
 ```typescript
 // Static: same expected trajectory for all items
@@ -474,10 +474,10 @@ The `createTrajectoryScorerCode()` function from `@mastra/evals/scorers/prebuilt
 
 The unified scorer evaluates four dimensions:
 
-1. **Accuracy** — Matches actual steps against expected steps (if `steps` is configured). Uses the `ordering` mode.
-2. **Efficiency** — Checks step budgets (`maxSteps`, `maxTotalTokens`, `maxTotalDurationMs`) and redundant calls (`noRedundantCalls`).
-3. **Blacklist** — Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
-4. **Tool failures** — Detects retry patterns, fallback patterns, and argument correction patterns.
+1. **Accuracy**: Matches actual steps against expected steps (if `steps` is configured). Uses the `ordering` mode.
+2. **Efficiency**: Checks step budgets (`maxSteps`, `maxTotalTokens`, `maxTotalDurationMs`) and redundant calls (`noRedundantCalls`).
+3. **Blacklist**: Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
+4. **Tool failures**: Detects retry and fallback patterns. It also detects argument correction patterns.
 
 The final score is a weighted combination of active dimensions, normalized by which dimensions are active. Default weights are accuracy 0.4, efficiency 0.3, tool failures 0.2, blacklist 0.1, but you can customize them via the `weights` option. Blacklist violations override everything to 0. When nested evaluations are present, the score is 70% top-level and 30% nested average.
 

package/.docs/reference/file-based-agents/instructions.md

@@ -27,7 +27,7 @@ Move conditional, large, or action-oriented guidance into [`tools/`](https://mas
 
 ## Dynamic instructions
 
-When the prompt needs to change per request, for example based on the current user or runtime context, set a dynamic `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+When the prompt needs to change per request, for example based on the current user or runtime context, set a runtime-defined `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
 
 ```typescript
 import { agentConfig } from '@mastra/core/agent'
@@ -49,6 +49,6 @@ Mastra reads `instructions.md` and inlines its contents into the generated code
 
 Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
 
-- A dynamic (function) `instructions` in `config.ts` wins over `instructions.md`.
+- A runtime-defined (function) `instructions` in `config.ts` wins over `instructions.md`.
 - Otherwise `instructions.md` wins over a static `instructions` string.
 - If neither is present, the build fails and names the agent directory.

package/.docs/reference/file-based-agents/logger.md

@@ -23,4 +23,4 @@ Mastra registers the logger before storage, observability, and file-based agents
 
 ## Precedence with code
 
-Code-registered logging wins over `logger.ts`. If you pass `logger` to `new Mastra({ logger })` in `src/mastra/index.ts` (or set `logger: false` to disable logging), `logger.ts` is ignored with a warning. Use `logger.ts` when one project-wide logger is enough; use code registration when setup depends on runtime wiring.
+Code-registered logging wins over `logger.ts`. If you pass `logger` to `new Mastra({ logger })` in `src/mastra/index.ts` (or set `logger: false` to disable logging), `logger.ts` is ignored with a warning. Use `logger.ts` when one project-wide logger is enough. Use code registration when setup depends on runtime wiring.

package/.docs/reference/file-based-agents/observability.md

@@ -29,4 +29,4 @@ export default new Observability({
 
 ## Precedence with code
 
-Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough. Use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/processors.md

@@ -45,7 +45,7 @@ If `config.inputProcessors` or `config.outputProcessors` is a function, discover
 
 ## Precedence with config
 
-Use `config.ts` for processors that need to be created dynamically or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
+Use `config.ts` for processors that need to be created at runtime or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
 
 Precedence is:
 

package/.docs/reference/file-based-agents/skills.md

@@ -40,7 +40,7 @@ For packaged skills, `description` is required in `SKILL.md` frontmatter. Flat m
 
 ## What gets loaded
 
-File-based Agents skills are read at build time and added to the generated bundle. The deployed agent doesn't need to read those skill files from disk at runtime.
+File-based Agent skills are added to the generated bundle at build time, so the deployed agent doesn't read them from disk.
 
 For packaged skills, Mastra reads:
 

package/.docs/reference/file-based-agents/storage.md

@@ -27,4 +27,4 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Precedence with code
 
-Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough. Use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/studio.md

@@ -53,4 +53,4 @@ The auth provider handles who the user is. For what the user can do after sign-i
 
 ## Precedence with code
 
-Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough; use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.
+Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough. Use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/subagents.md

@@ -2,7 +2,7 @@
 
 # Subagents
 
-A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
+A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
 Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
 

package/.docs/reference/file-based-agents/tools.md

@@ -37,7 +37,7 @@ Use one file per tool. Name the file after the action the model should take:
 
 - Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
 - Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
-- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
+- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`. Discovery ignores those files.
 - Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
 
 Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.

package/.docs/reference/file-based-agents/workspace.md

@@ -56,7 +56,7 @@ The workspace filesystem controls what file tools can read and write. The sandbo
 
 ## Seed files
 
-Add a `workspace/` directory to ship starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
+Add a `workspace/` directory to include starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
 
 ```text
 src/mastra/agents/weather/

package/.docs/reference/logging/pino-logger.md

@@ -2,7 +2,7 @@
 
 # PinoLogger
 
-A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
+A Logger instance is created using `new PinoLogger()` and provides methods to record events at severity levels.
 
 ## Usage example
 
@@ -86,7 +86,7 @@ const logger = new MastraPinoWithAudit({
 export const mastra = new Mastra({ logger })
 ```
 
-Numeric values follow Pino’s ordering (built-in levels use 10–60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
+Numeric values follow Pino’s ordering (built-in levels use 10 to 60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
 
 ## File transport (structured logs)
 
@@ -114,7 +114,7 @@ fileLogger.warn('Low disk space', {
 
 ## Upstash transport (remote log drain)
 
-Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
+Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. It supports centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
 
 ```typescript
 import { UpstashTransport } from '@mastra/loggers/upstash'

package/.docs/reference/memory/clone-utilities.md

@@ -2,7 +2,7 @@
 
 # Cloned thread utilities
 
-The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, navigate clone relationships, and track clone history.
+The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, traverse clone relationships, and track clone history.
 
 ## `isClone()`
 

package/.docs/reference/memory/cloneThread.md

@@ -2,7 +2,7 @@
 
 # Memory.cloneThread()
 
-The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. This enables creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
+The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. It supports creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
 
 ## Usage example
 
@@ -125,7 +125,7 @@ Pass the cloned `thread.id` and `thread.resourceId` to `agent.generate()` to con
 
 ## Vector embeddings
 
-When the Memory instance has semantic recall enabled with a vector store and embedder configured, `cloneThread()` automatically creates vector embeddings for all cloned messages. This ensures that semantic search works correctly on the cloned thread.
+When the Memory instance has semantic recall enabled with a vector store and embedder configured, `cloneThread()` automatically creates vector embeddings for all cloned messages. It ensures that semantic search works correctly on the cloned thread.
 
 In this example, `embeddingModel` is the embedding model configured for the project.
 
@@ -170,4 +170,4 @@ When [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
 - **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
 - **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
 
-Only the current (most recent) OM generation is cloned — older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.
+Only the current (most recent) OM generation is cloned. Older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

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

@@ -19,7 +19,7 @@ const result = await memory.listThreads({
 
 Use `perPage: false` to retrieve all matching threads at once.
 
-> **Warning:** Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+> **Warning:** Use pagination, especially for large datasets. Use this option cautiously.
 
 ```typescript
 const result = await memory.listThreads({

package/.docs/reference/memory/memory-class.md

@@ -2,7 +2,7 @@
 
 # Memory class
 
-The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
 
 ## Usage example