@mastra/mcp-docs-server 1.2.2-alpha.1 → 1.2.2-alpha.10

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

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

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

@@ -1,6 +1,6 @@
 # ![Together AI logo](https://models.dev/logos/togetherai.svg)Together AI
 
-Access 24 Together AI models through Mastra's model router. Authentication is handled automatically using the `TOGETHER_API_KEY` environment variable.
+Access 25 Together AI models through Mastra's model router. Authentication is handled automatically using the `TOGETHER_API_KEY` environment variable.
 
 Learn more in the [Together AI documentation](https://docs.together.ai/docs/serverless-models).
 
@@ -56,6 +56,7 @@ for await (const chunk of stream) {
 | `togetherai/Qwen/Qwen3.7-Max`                         | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `togetherai/zai-org/GLM-5`                            | 203K    |       |           |       |       |       | $1         | $3          |
 | `togetherai/zai-org/GLM-5.1`                          | 203K    |       |           |       |       |       | $1         | $4          |
+| `togetherai/zai-org/GLM-5.2`                          | 262K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 
@@ -84,7 +85,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "togetherai/zai-org/GLM-5.1"
+      ? "togetherai/zai-org/GLM-5.2"
       : "togetherai/LiquidAI/LFM2-24B-A2B";
   }
 });

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

@@ -47,6 +47,10 @@ export const supportAgent = new Agent({
 
 **resolveResourceId** (`(ctx: ResolveResourceIdContext) => string | Promise<string>`): Decide which \`resourceId\` owns resource-level memory for a channel thread, separately from who sent the message. Runs only when a new thread is created; reused threads keep their stored owner and never call the hook. Return \`ctx.defaultResourceId\` (\`${platform}:${message.author.userId}\`) to keep the built-in behavior.
 
+**waitUntil** (`(promise: Promise<unknown>) => void`): Platform \`waitUntil\` function. Required on Vercel so background agent runs survive after the webhook returns 200. On Vercel pass \`waitUntil\` from \`@vercel/functions\`. Cloudflare Workers and Netlify Functions are detected automatically from the request context. AWS Lambda does not need \`waitUntil\` because it waits for the event loop to drain naturally.
+
+**resolveWaitUntil** (`(c: Context) => ((promise: Promise<unknown>) => void) | undefined`): Resolver for runtimes where \`waitUntil\` lives on the Hono request context but is not covered by the built-in helper. Resolution order: bare \`waitUntil\` → \`resolveWaitUntil(c)\` → default (Cloudflare Workers, Netlify).
+
 ## Per-adapter options
 
 Wrap an adapter in a `ChannelAdapterConfig` object to set per-adapter options:

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

@@ -203,9 +203,13 @@ interface PrepareResult {
 
 **activeTools** (`string[]`): Restricts execution to the named subset of the agent's tools.
 
-**modelSettings** (`object`): Model-specific settings such as temperature.
+**modelSettings** (`object`): Model-specific settings such as temperature. Credential-bearing headers (\`Authorization\`, \`X-Api-Key\`, and similar) are stripped from the serialized snapshot before it crosses process boundaries.
 
-**requireToolApproval** (`boolean`): Require approval for all tool calls, which suspends the run until resumed.
+**stopWhen** (`AgentExecutionOptions['stopWhen']`): Predicate or composition that ends the agentic loop early. The closure rides on the in-process run registry; cross-process resumes degrade to \`maxSteps\` only.
+
+**system** (`string | string[]`): Additional system message appended after the agent instructions and before user messages.
+
+**requireToolApproval** (`boolean | ((args: { toolName: string; args: unknown; requestContext: RequestContext; workspace?: string }) => boolean | Promise<boolean>)`): Require approval for tool calls. Pass \`true\` or \`false\` to gate all or none, or a function for per-call policy. Function-form policies live on the in-process run registry; cross-process resumes fall back to a \`true\` shadow.
 
 **autoResumeSuspendedTools** (`boolean`): Automatically resume tools that suspended, instead of waiting for an external \`resume()\` call.
 
@@ -217,10 +221,26 @@ interface PrepareResult {
 
 **structuredOutput** (`object`): Structured output configuration.
 
-**untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations until the agent is idle. Pass \`true\` for the default 5-minute idle timeout, or \`{ maxIdleMs }\` to customise. Equivalent to the deprecated \`streamUntilIdle()\` method.
+**untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations until the agent is idle. Pass \`true\` for the default 5-minute idle timeout, or \`{ maxIdleMs }\` to customise. Equivalent to the deprecated \`streamUntilIdle()\` method. Also supported on \`resume()\`.
+
+**disableBackgroundTasks** (`boolean`): Disable background-task dispatch for this run. Background-eligible tools execute inline instead.
+
+**tracingOptions** (`AgentExecutionOptions['tracingOptions']`): Tracing metadata, tags, trace ID, parent span ID, and \`requestContextKeys\` forwarded to the agent and model spans. Fully JSON-serializable.
+
+**actor** (`AgentExecutionOptions['actor']`): Per-call actor signal forwarded to FGA checks and tool execution.
+
+**transform** (`AgentExecutionOptions['transform']`): Per-invocation tool payload transform policy. The \`transformToolPayload\` closure lives on the in-process run registry; only the JSON-safe \`targets\` shadow is serialized.
+
+**prepareStep** (`AgentExecutionOptions['prepareStep']`): Per-step preparation hook invoked as a \`PrepareStepProcessor\` at the start of every iteration. Closure-only — stored on the in-process run registry. Cross-process resumes lose the hook.
+
+**isTaskComplete** (`AgentExecutionOptions['isTaskComplete']`): Per-call completion policy. Scorer instances and \`onComplete\` live on the in-process run registry; the JSON-safe primitives (\`strategy\`, \`timeout\`, \`parallel\`, \`suppressFeedback\`, \`scorerNames\`) are serialized for cross-process observability.
+
+**delegation** (`AgentExecutionOptions['delegation']`): Sub-agent delegation hooks (\`onDelegationStart\`, \`onDelegationComplete\`, \`messageFilter\`). Callbacks are baked into the sub-agent tool wrappers at prepare time. Cross-process resumes lose the callbacks.
 
 **versions** (`object`): Version overrides for sub-agent delegation.
 
+**abortSignal** (`AbortSignal`): External abort signal. Forwarded to the durable run's internal \`AbortController\`, so either source can cancel the run. Cross-process resumes cannot recover the signal — pass a fresh one to \`resume()\` if you need post-resume abortability.
+
 **onChunk** (`(chunk: ChunkType) => void | Promise<void>`): Called for each streamed chunk.
 
 **onStepFinish** (`(result: AgentStepFinishEventData) => void | Promise<void>`): Called when a step in the agentic loop finishes.
@@ -231,6 +251,10 @@ interface PrepareResult {
 
 **onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): Called when the run suspends, for example for tool approval.
 
+**onAbort** (`AgentExecutionOptions['onAbort']`): Called when the run is aborted via \`abortSignal\` or \`result.abort()\`.
+
+**onIterationComplete** (`AgentExecutionOptions['onIterationComplete']`): Called after every agentic-loop iteration with the latest \`messageList\`, \`finishReason\`, and \`isFinal\` flag. Observation-only on durable agents: returning \`continue: false\` or feedback does not influence the loop.
+
 `resume()` and `observe()` accept the same lifecycle callbacks (`onChunk`, `onStepFinish`, `onFinish`, `onError`, `onSuspended`). `observe()` also accepts an `offset` to control where replay starts.
 
 ## DurableAgentStreamResult
@@ -245,6 +269,7 @@ interface DurableAgentStreamResult<OUTPUT = undefined> {
   threadId?: string
   resourceId?: string
   cleanup: () => void
+  abort: () => void
 }
 ```
 
@@ -260,6 +285,8 @@ interface DurableAgentStreamResult<OUTPUT = undefined> {
 
 **cleanup** (`() => void`): Unsubscribes from PubSub and clears registry entries for the run. Call it when done with the run.
 
+**abort** (`() => void`): Aborts the run by flipping the internal \`AbortController\`. Surfaces as an \`AbortError\` inside the durable LLM-execution step and fires the \`onAbort\` callback. Safe to call after the run has finished — a no-op in that case.
+
 ## Related
 
 - [`createInngestAgent()`](https://mastra.ai/reference/agents/inngest-agent)

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

@@ -170,7 +170,7 @@ const response = await agent.generate('Help me organize my day', {
 
 **options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of tool names that should be active during execution. If undefined, all available tools are active.
 
-**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
 
 **options.prepareStep** (`PrepareStepFunction`): Callback function called before each step of multi-step execution.
 

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

@@ -0,0 +1,51 @@
+# workflowSnapshotToStream()
+
+Converts a `WorkflowState` object (as returned by `workflow.getWorkflowRunById()`) into a `ReadableStream` of AI SDK UIMessage data parts. The stream contains the same `WorkflowDataPart` and `WorkflowStepDataPart` chunks that the live [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route) produces.
+
+Use this when you want to display a completed or suspended workflow run using the same UI components that render live workflow streams.
+
+## Usage example
+
+Next.js App Router endpoint that replays a past workflow run as a stream:
+
+```typescript
+import { workflowSnapshotToStream } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const runId = searchParams.get('runId')!
+
+  const workflowRun = await mastra.getWorkflow('myWorkflow').getWorkflowRunById(runId)
+
+  if (!workflowRun) {
+    return new Response('Not found', { status: 404 })
+  }
+
+  const stream = workflowSnapshotToStream(workflowRun)
+  return createUIMessageStreamResponse({ stream })
+}
+```
+
+## Parameters
+
+**workflowRun** (`WorkflowState`): The workflow run state object, as returned by \`getWorkflowRunById()\` or the workflow runs API. Contains \`runId\`, \`workflowName\`, \`status\`, and \`steps\`.
+
+## Returns
+
+`ReadableStream` — A stream of AI SDK UIMessage data parts containing:
+
+- A `start` marker
+- A `WorkflowDataPart` with the overall workflow status and all step summaries
+- A `WorkflowStepDataPart` for each step with its full output
+- A `finish` marker
+
+Pass this stream to [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) or `createUIMessageStream()` from the AI SDK.
+
+## Related
+
+- [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route): Stream live workflow runs
+- [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream): Framework-agnostic handler for live workflow streaming
+- [`toAISdkStream()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-stream): Convert live Mastra streams to AI SDK format
+- [`toAISdkMessages()`](https://mastra.ai/reference/ai-sdk/to-ai-sdk-messages): Convert stored agent messages to AI SDK format

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

@@ -666,6 +666,14 @@ Target a specific Mastra server URL.
 mastra api --url https://example.com agent list
 ```
 
+#### `--server-api-prefix <prefix>`
+
+Set the API route prefix of the target server. Defaults to `/api`. Use this when the server is mounted under a custom prefix (for example a `@mastra/fastify` `MastraServer` with `prefix: "/api/mastra-studio"`), the same way `mastra studio` accepts `--server-api-prefix`. You can also set the `MASTRA_API_PREFIX` environment variable instead of passing the flag.
+
+```bash
+mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list
+```
+
 #### `--header <"Key: Value">`
 
 Send a custom HTTP header. Repeat the flag to send multiple headers.

package/.docs/reference/evals/checks.md

@@ -0,0 +1,210 @@
+# Quick Checks
+
+Quick Checks are zero-LLM, composable micro-scorers for common assertions. They plug into the existing `scorers: [...]` array anywhere scorers are used — in `runEvals`, live scoring, experiments, and Studio.
+
+Internally they are standard `createScorer()` instances, so they have the same observability, storage, and pipeline integration as any other scorer.
+
+## Usage example
+
+```typescript
+import { checks } from '@mastra/evals/checks'
+import { runEvals } from '@mastra/core/evals'
+import { myAgent } from '../agents'
+
+const result = await runEvals({
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  target: myAgent,
+  scorers: [
+    checks.includes('sunny'),
+    checks.calledTool('get_weather'),
+    checks.toolOrder(['get_weather', 'summarize']),
+    checks.noToolErrors(),
+  ],
+})
+
+console.log(result.scores)
+```
+
+## Text checks
+
+### `checks.includes(expected, options?)`
+
+Scores 1 if the agent's output text contains the expected substring, 0 otherwise.
+
+```typescript
+checks.includes('sunny')
+checks.includes('Sunny', { ignoreCase: false })
+```
+
+**expected** (`string`): Substring to search for in the output.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if found, `0` otherwise.
+
+### `checks.excludes(unwanted, options?)`
+
+Scores 1 if the agent's output text does NOT contain the substring, 0 otherwise.
+
+```typescript
+checks.excludes('error')
+checks.excludes('Error', { ignoreCase: false })
+```
+
+**unwanted** (`string`): Substring that must not appear in the output.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if absent, `0` otherwise.
+
+### `checks.equals(expected, options?)`
+
+Scores 1 if the output text exactly equals the expected string after optional normalization.
+
+```typescript
+checks.equals('Hello, world!')
+checks.equals('Hello', { ignoreCase: false })
+```
+
+**expected** (`string`): Exact string the output must match.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if equal, `0` otherwise.
+
+### `checks.matches(pattern, options?)`
+
+Scores 1 if the output matches the given regular expression.
+
+```typescript
+checks.matches(/\d+°[FC]/)
+checks.matches(/^hello$/, { exact: true })
+```
+
+**pattern** (`RegExp`): Regular expression to test against the output.
+
+**options.exact** (`boolean`): Anchor the pattern to match the entire output (adds ^ and $). (Default: `false`)
+
+Returns: `1` if matched, `0` otherwise.
+
+### `checks.similarity(expected, options?)`
+
+Returns the string similarity score (0-1) between the output and an expected string using the Dice coefficient. When a `threshold` is set, returns binary 1/0 instead.
+
+```typescript
+checks.similarity('Sunny, 72°F')
+checks.similarity('Sunny, 72°F', { threshold: 0.7 })
+```
+
+**expected** (`string`): Reference string to compare against.
+
+**options.threshold** (`number`): Minimum similarity score (0-1) to return 1. When omitted, returns the raw similarity score.
+
+**options.ignoreCase** (`boolean`): Case-insensitive comparison. (Default: `true`)
+
+Returns: Raw similarity score (0-1), or binary `1`/`0` when `threshold` is set.
+
+## Tool call checks
+
+### `checks.calledTool(toolName, options?)`
+
+Scores 1 if the agent called the specified tool at least the required number of times.
+
+```typescript
+checks.calledTool('get_weather')
+checks.calledTool('search', { times: 2 })
+```
+
+**toolName** (`string`): Name of the tool to look for.
+
+**options.times** (`number`): Minimum number of times the tool must be called. (Default: `1`)
+
+Returns: `1` if called at least `times` times, `0` otherwise.
+
+### `checks.didNotCall(toolName)`
+
+Scores 1 if the agent did NOT call the specified tool.
+
+```typescript
+checks.didNotCall('delete_user')
+```
+
+**toolName** (`string`): Name of the tool that must not appear.
+
+Returns: `1` if the tool was not called, `0` otherwise.
+
+### `checks.toolOrder(expectedOrder)`
+
+Scores 1 if the tools were called in the specified order. Uses relaxed matching — other tool calls between the expected tools are allowed.
+
+```typescript
+checks.toolOrder(['search', 'summarize', 'respond'])
+```
+
+**expectedOrder** (`string[]`): Tool names in the expected calling sequence. Must appear as a subsequence of the actual tool calls.
+
+Returns: `1` if the expected order is satisfied, `0` otherwise.
+
+### `checks.maxToolCalls(max)`
+
+Scores 1 if the agent used no more than `max` tool calls.
+
+```typescript
+checks.maxToolCalls(5)
+```
+
+**max** (`number`): Maximum number of tool calls allowed.
+
+Returns: `1` if within the limit, `0` otherwise.
+
+### `checks.usedNoTools()`
+
+Scores 1 if the agent made no tool calls at all.
+
+```typescript
+checks.usedNoTools()
+```
+
+Returns: `1` if no tools were called, `0` otherwise.
+
+### `checks.noToolErrors()`
+
+Scores 1 if none of the tool invocations resulted in an error state. Detects both error results (`result.error` present) and incomplete tool calls (`state === 'call'`).
+
+```typescript
+checks.noToolErrors()
+```
+
+Returns: `1` if all tool calls succeeded, `0` otherwise.
+
+## Combining checks with other scorers
+
+Checks compose with LLM-based and code-based scorers in the same `scorers` array:
+
+```typescript
+import { checks } from '@mastra/evals/checks'
+import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
+import { runEvals } from '@mastra/core/evals'
+import { myAgent } from '../agents'
+
+const result = await runEvals({
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  target: myAgent,
+  scorers: [
+    // Zero-LLM checks
+    checks.includes('Brooklyn'),
+    checks.calledTool('get_weather'),
+    checks.noToolErrors(),
+    // LLM-based scorer
+    createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+  ],
+})
+```
+
+## Related
+
+- [Quick Checks overview](https://mastra.ai/docs/evals/quick-checks)
+- [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers)
+- [`createScorer()` reference](https://mastra.ai/reference/evals/create-scorer)
+- [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals)
+- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers)

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

@@ -29,13 +29,34 @@ console.log(`Average scores:`, result.scores)
 console.log(`Processed ${result.summary.totalItems} items`)
 ```
 
+### With gates and thresholds
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { faithfulnessScorer } from './scorers'
+
+const result = await runEvals({
+  target: myAgent,
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
+  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }, checks.includes('Brooklyn')],
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+result.gateResults // [{ id, passed, score }]
+result.thresholdResults // [{ id, passed, averageScore, threshold }]
+```
+
 ## Parameters
 
 **target** (`Agent | Workflow`): The agent or workflow to evaluate.
 
 **data** (`RunEvalsDataItem[]`): Array of test cases with input data and optional ground truth.
 
-**scorers** (`MastraScorer[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. A flat array applies all scorers to the raw output. For agents, an \`AgentScorerConfig\` object separates agent-level and trajectory scorers. For workflows, a \`WorkflowScorerConfig\` object specifies scorers for the workflow, individual steps, and trajectory.
+**scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. Each entry is either a bare \`MastraScorer\` or \`{ scorer, threshold }\` for threshold tracking. An \`AgentScorerConfig\` object separates agent-level and trajectory scorers. A \`WorkflowScorerConfig\` object specifies scorers for the workflow, individual steps, and trajectory.
+
+**gates** (`MastraScorer[]`): Scorers that must score 1.0 for the run to pass. If any gate averages below 1.0 across data items, the verdict is \`failed\`. Gates run before regular scorers on each data item.
 
 **targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState).
 
@@ -83,8 +104,55 @@ For workflows, use `WorkflowScorerConfig` to specify scorers at different levels
 
 **summary.totalItems** (`number`): Total number of test cases processed.
 
+**verdict** (`'passed' | 'scored' | 'failed'`): Present when \`gates\` or threshold-bearing scorers are provided. \`passed\` = all gates and thresholds met. \`scored\` = gates passed but a threshold was missed. \`failed\` = at least one gate did not score 1.0.
+
+**gateResults** (`GateResult[]`): Per-gate results averaged across all data items. Each entry has \`id\`, \`passed\` (boolean), and \`score\` (0–1).
+
+**thresholdResults** (`ThresholdResult[]`): Per-threshold-scorer results averaged across all data items. Each entry has \`id\`, \`passed\`, \`averageScore\`, and \`threshold\`.
+
+## ScorerEntry
+
+A scorer entry in the `scorers` array can be either a bare scorer or a scorer with a threshold:
+
+**scorer** (`MastraScorer`): The scorer instance.
+
+**threshold** (`number | { min?: number; max?: number }`): A number implies minimum threshold (score at or above passes). Use \`{ min, max }\` for range-based checks — e.g. \`{ max: 0.3 }\` for scorers like hallucination where a high score is bad. Both \`min\` and \`max\` must be between 0 and 1.
+
 ## Examples
 
+### Gates and verdict
+
+Use `gates` for hard pass/fail requirements and `{ scorer, threshold }` for tracked quality metrics:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+
+const result = await runEvals({
+  target: weatherAgent,
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
+  scorers: [
+    { scorer: faithfulnessScorer, threshold: 0.7 }, // min threshold (number shorthand)
+    { scorer: hallucinationScorer, threshold: { max: 0.3 } }, // max threshold (high = bad)
+    { scorer: toneScorer, threshold: { min: 0.5, max: 0.9 } }, // range threshold
+    checks.includes('Brooklyn'), // bare scorer, no threshold
+  ],
+})
+
+if (result.verdict === 'failed') {
+  console.log(
+    'Gate failures:',
+    result.gateResults?.filter(g => !g.passed),
+  )
+} else if (result.verdict === 'scored') {
+  console.log(
+    'Threshold misses:',
+    result.thresholdResults?.filter(t => !t.passed),
+  )
+}
+```
+
 ### Agent Evaluation
 
 ```typescript
@@ -246,6 +314,8 @@ const result = await runEvals({
 
 ## Related
 
+- [Gates and Verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Conceptual guide to severity semantics
+- [Quick Checks](https://mastra.ai/reference/evals/checks): Zero-LLM composable micro-scorers
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer): Create custom scorers for experiments
 - [MastraScorer](https://mastra.ai/reference/evals/mastra-scorer): Learn about scorer structure and methods
 - [Trajectory Accuracy](https://mastra.ai/reference/evals/trajectory-accuracy): Built-in trajectory evaluation scorers