@mastra/mcp-docs-server 1.2.7-alpha.8 → 1.2.8-alpha.0

package/.docs/docs/agent-builder/integrations.md

@@ -8,6 +8,17 @@ Tool providers let Builder-created agents call tools from third-party apps such
 
 This page covers what's specific to the Builder: setting up connections, choosing a connection scope, and managing connections. To register a provider and enable its toolkits, see [Tools](https://mastra.ai/docs/editor/tools).
 
+## Setup at a glance
+
+To connect a toolkit like Gmail and use it from a Builder agent:
+
+1. [Register a tool provider](#register-a-tool-provider) on `MastraEditor` with your Composio API key.
+2. [Set up a Composio auth config](#set-up-a-composio-auth-config) for the toolkit and enable it.
+3. [Connect the toolkit](#connect-a-toolkit) from the Builder and complete the OAuth flow.
+4. [Choose a connection scope](#connection-scope) if the default author-owned account isn't what you want.
+
+The rest of this page covers each step in detail.
+
 ## Prerequisites
 
 Before agents can use integration tools in the Builder:
@@ -42,6 +53,8 @@ export const mastra = new Mastra({
 
 Each provider's toolkits become available in the Builder once it's registered. Use `allowedToolkits` to restrict which toolkits the provider exposes — by slug, such as `gmail` or `googlecalendar`. Omit it to expose every toolkit the provider offers. To add another provider, import it and add another entry to `toolProviders`. For the full list of providers and their options, see [Tools — Integration providers](https://mastra.ai/docs/editor/tools).
 
+`ComposioToolProvider` needs a Composio **project** API key (the `x-api-key` type from a project's settings in the [Composio dashboard](https://dashboard.composio.dev)). Store it in an environment variable, as shown with `COMPOSIO_API_KEY` above.
+
 ## Set up a Composio auth config
 
 Each toolkit a user can connect needs its own auth config in the [Composio dashboard](https://dashboard.composio.dev). An auth config defines how Composio authenticates with an app — its OAuth client, scopes, and credentials. Each toolkit needs its own because requirements vary by app: some share common OAuth methods, while others need extra setup. Without an enabled config, the connection flow fails.
@@ -52,7 +65,7 @@ Each toolkit a user can connect needs its own auth config in the [Composio dashb
 
 Keep exactly one auth config enabled per toolkit. When a user connects the toolkit, the provider resolves the single enabled config for that toolkit and starts the OAuth flow against it.
 
-> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. Enable exactly one auth config per toolkit you expose in the Builder.
+> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. With no enabled config, the connection flow fails with an error like `No ENABLED auth config for toolkit "github"` — enable one in the Composio dashboard to fix it. Enable exactly one auth config per toolkit you expose in the Builder.
 
 ## Connect a toolkit
 
@@ -65,7 +78,36 @@ The connected account is bound to the agent, and its tools are ready to use on t
 
 ## Connection scope
 
-When you select a toolkit's tools for an agent, you also pin a connection. The connection determines which account each tool call uses at runtime, with a scope that controls who shares the credential. Today connections are `per-author`: the connection belongs to the agent's author, and any invoker runs the agent with the author's account.
+Each connection determines which account a tool call uses at runtime, and its _scope_ controls who shares that credential. A scope maps each call to a _bucket_ — the identity partition that a connected account is stored under. Scope is a tenancy decision made by you, the app author, not by the end user connecting an account — so you set it on the provider, not in the Builder UI.
+
+- `per-author` (default): the connection belongs to the agent's author. Any invoker runs the agent with the author's account. Use this for personal agents or a single shared team account.
+- `shared`: every caller uses one shared bucket, regardless of who invokes the agent. Use this for a platform-owned account that all users should share.
+- `caller-supplied`: each call is bucketed by the caller's `resourceId`, read from the request context. Use this for multi-tenant SaaS, where the host app authenticates the end user upstream and each tenant should use their own connected account.
+
+Set `defaultScope` on the provider to apply a scope to every connection authorized against it:
+
+```typescript
+const composio = new ComposioToolProvider({
+  apiKey: process.env.COMPOSIO_API_KEY!,
+  allowedToolkits: ['github'],
+  defaultScope: 'caller-supplied',
+})
+```
+
+With `caller-supplied`, the host app must forward a `resourceId` on every request so each tenant lands in its own bucket. Set `mapUserToResourceId` on the server's auth config to derive the `resourceId` from the authenticated user, so every request carries it automatically:
+
+```typescript
+export const mastra = new Mastra({
+  server: {
+    auth: {
+      authenticateToken: async token => verifyToken(token),
+      mapUserToResourceId: user => user.id,
+    },
+  },
+})
+```
+
+> **Warning:** When a `caller-supplied` connection runs without a `resourceId`, every tenant falls back to a single shared `default` bucket. All callers then share one set of credentials, which can expose one tenant's connected account to another. Always wire `mapUserToResourceId` (or otherwise set `resourceId` on the request context) for multi-tenant deployments.
 
 ## Related
 

package/.docs/docs/agent-builder/skill-registries.md

@@ -23,9 +23,7 @@ new MastraEditor({
 })
 ```
 
-The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent.
-
-> **Note:** See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
+The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
 
 ## Related
 

package/.docs/docs/agent-controller/overview.md

@@ -88,7 +88,7 @@ await agentController.selectOrCreateThread()
 await agentController.sendMessage({ content: 'Hello!' })
 ```
 
-> **Note:** Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
+Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
 
 ## Architecture
 

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

@@ -133,9 +133,7 @@ agentController.subscribe(event => {
 })
 ```
 
-This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view.
-
-> **Note:** Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
+This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view. Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
 
 ## Related
 

package/.docs/docs/agents/code-mode.md

@@ -94,7 +94,7 @@ For `createCodeMode()` to work well, keep these tips in mind:
 - Keep tools focused, so each does one thing well and the model composes them in code.
 - Code mode helps most when calls can be parallelized with `Promise.all`.
 
-> **Note:** Visit the [`createCodeMode()` reference](https://mastra.ai/reference/tools/create-code-mode) for configuration options, return values, result shape, and instructions inspection.
+Visit the [`createCodeMode()` reference](https://mastra.ai/reference/tools/create-code-mode) for configuration options, return values, result shape, and instructions inspection.
 
 ## Scoping tools across multiple code tools
 
@@ -126,6 +126,22 @@ const agent = new Agent({
 
 The generated code for `sales_code` can't call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
 
+## Remote sandboxes
+
+By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/reference/workspace/e2b-sandbox)), where the host paths don't exist.
+
+Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the shipped `E2BCodeModeTransport` as the second argument to `createCodeMode`:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'
+
+const { tool, instructions } = createCodeMode(
+  { tools, sandbox: new E2BSandbox() },
+  new E2BCodeModeTransport(),
+)
+```
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)

package/.docs/docs/agents/guardrails.md

@@ -29,7 +29,7 @@ export const normalizedAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`UnicodeNormalizer()`](https://mastra.ai/reference/processors/unicode-normalizer) reference for a full list of configuration options.
+Visit [`UnicodeNormalizer()`](https://mastra.ai/reference/processors/unicode-normalizer) reference for a full list of configuration options.
 
 ### Prevent prompt injection
 
@@ -52,7 +52,7 @@ export const secureAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`PromptInjectionDetector()`](https://mastra.ai/reference/processors/prompt-injection-detector) reference for a full list of configuration options.
+Visit [`PromptInjectionDetector()`](https://mastra.ai/reference/processors/prompt-injection-detector) reference for a full list of configuration options.
 
 ### Detect and translate language
 
@@ -75,7 +75,7 @@ export const multilingualAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`LanguageDetector()`](https://mastra.ai/reference/processors/language-detector) reference for a full list of configuration options.
+Visit [`LanguageDetector()`](https://mastra.ai/reference/processors/language-detector) reference for a full list of configuration options.
 
 ## Output processors
 
@@ -101,7 +101,7 @@ export const batchedAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`BatchPartsProcessor()`](https://mastra.ai/reference/processors/batch-parts-processor) reference for a full list of configuration options.
+Visit [`BatchPartsProcessor()`](https://mastra.ai/reference/processors/batch-parts-processor) reference for a full list of configuration options.
 
 ### Scrub system prompts
 
@@ -128,7 +128,7 @@ const scrubbedAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
+Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
 
 > **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/mastra-server) for details.
 
@@ -158,7 +158,7 @@ export const moderatedAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`ModerationProcessor()`](https://mastra.ai/reference/processors/moderation-processor) reference for a full list of configuration options.
+Visit [`ModerationProcessor()`](https://mastra.ai/reference/processors/moderation-processor) reference for a full list of configuration options.
 
 ### Detect and redact PII
 
@@ -184,7 +184,7 @@ export const privateAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
+Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
 
 ### Enforce cost limits
 
@@ -206,7 +206,7 @@ export const budgetedAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
+Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
 
 ## Processor strategies
 

package/.docs/docs/agents/overview.md

@@ -151,9 +151,9 @@ export const mastra = new Mastra({
 
 Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features.
 
-> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
+Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
-> **Note:** Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
+> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
 
 ## Use your agent
 

package/.docs/docs/agents/processors.md

@@ -850,10 +850,16 @@ const agent = new Agent({
 
 The retry mechanism:
 
-- Only works in `processOutputStep()` and `processInputStep()` methods
+- Works in `processOutputStep()` and `processInputStep()` methods
 - Replays the step with the abort reason added as context for the LLM
 - Tracks retry count via the `retryCount` parameter
-- Respects `maxProcessorRetries` limit on the agent
+- Requires an explicit `maxProcessorRetries` limit on the agent or call
+
+### Error processor retry limits
+
+`processAPIError()` has a separate default: when `errorProcessors` are configured and `maxProcessorRetries` is omitted, the runtime allows up to `10` retries. Set the limit explicitly when you need a bounded retry budget.
+
+For `StreamErrorRetryProcessor`, also set its `maxRetries` to the same value. Its own default is `1`, which can otherwise be lower than the agent cap. Keep model retries at `0` when the processor is the only retry mechanism for a request.
 
 ### Violation callbacks
 
@@ -908,7 +914,7 @@ For `agent.generate()`, the result exposes the same information as `result.tripw
 
 `abort` accepts a second options argument:
 
-- `retry: true` asks the agent to retry instead of ending. Retries require `maxProcessorRetries` to be set on the agent or call.
+- `retry: true` asks the agent to retry instead of ending. Input and output processor retries require `maxProcessorRetries` to be set on the agent or call.
 - `metadata` attaches structured data to the `tripwire` chunk so downstream consumers can branch on categories like `pii`, `quality`, or `moderation`.
 
 ## API error handling

package/.docs/docs/agents/skills.md

@@ -69,9 +69,7 @@ export const releaseChecklist = createSkill({
 })
 ```
 
-The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, like `references/` files in a filesystem skill.
-
-> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, like `references/` files in a filesystem skill. Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
 
 ## Filesystem path skills
 
@@ -179,7 +177,7 @@ for (const meta of allSkills) {
 }
 ```
 
-> **Note:** Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
+Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
 
 ## Related
 

package/.docs/docs/agents/structured-output.md

@@ -103,7 +103,7 @@ const response = await testAgent.generate('Help me plan my day.', {
 console.log(response.object)
 ```
 
-> **Note:** Visit [`.generate()`](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
+Visit [`.generate()`](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
 
 **Example output:** The `response.object` will contain the structured data as defined by the schema.
 

package/.docs/docs/agents/supervisor-agents.md

@@ -226,9 +226,7 @@ How it works:
 2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
 3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
 
-This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation.
-
-> **Note:** Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
+This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
 
 ## Tool approval propagation
 

package/.docs/docs/agents/using-tools.md

@@ -4,6 +4,8 @@
 
 Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
 
+**For AI agents:** Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
+
 ## When to use tools
 
 Use tools when an agent needs additional context or information from remote resources, or when it needs to run code that performs a specific operation. This includes tasks a model can't reliably handle on its own, such as fetching live data or returning consistent, well-defined outputs.
@@ -38,9 +40,7 @@ export const weatherTool = createTool({
 })
 ```
 
-When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
-
-> **Note:** Visit the [`createTool`](https://mastra.ai/reference/tools/create-tool) reference for more information on available properties, configurations, and examples.
+When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool. Visit the [`createTool`](https://mastra.ai/reference/tools/create-tool) reference for more information on available properties, configurations, and examples.
 
 To make a tool available to an agent, add it to the `tools` property on the `Agent` class. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
 
@@ -359,7 +359,7 @@ await agent.generate('Check the forecast', {
 })
 ```
 
-> **Note:** See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for all runtime options including `toolsets`, `clientTools`, and `prepareStep`.
+See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for all runtime options including `toolsets`, `clientTools`, and `prepareStep`.
 
 ## Control `toolName` in stream responses
 

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

@@ -99,9 +99,7 @@ const browser = new AgentBrowser({
 })
 ```
 
-This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details.
-
-> **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
+This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details. See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
 
 ## Related
 

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

@@ -140,9 +140,7 @@ npm install -g browse
 browse skills install
 ```
 
-CDP flag: `--ws`
-
-> **Note:** See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
+CDP flag: `--ws` See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
 
 ## Related
 

package/.docs/docs/browser/stagehand.md

@@ -146,7 +146,7 @@ const browser = new StagehandBrowser({
 })
 ```
 
-> **Note:** See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
+See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
 
 ## Recording
 

package/.docs/docs/capabilities/channels/overview.md

@@ -194,9 +194,7 @@ With this configuration:
 - A user pastes a YouTube link and the agent watches and discusses the video.
 - A user pastes an imgur link and the agent sees the image directly.
 
-By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupported types are described as text summaries so the agent knows about the file without failing on models that reject them.
-
-> **Note:** See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced MIME types.
+By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupported types are described as text summaries so the agent knows about the file without failing on models that reject them. See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced MIME types.
 
 ## Serverless deployment
 

package/.docs/docs/deployment/mastra-server.md

@@ -14,9 +14,7 @@ Run the build command from your project root:
 mastra build
 ```
 
-This creates a `.mastra` directory containing your production-ready server.
-
-> **Info:** Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+This creates a `.mastra` directory containing your production-ready server. Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build output
 
@@ -59,7 +57,7 @@ The `mastra start` command provides additional features:
 - Provides helpful error messages for missing modules
 - Handles process signals for graceful shutdown
 
-> **Info:** Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build configuration
 

package/.docs/docs/editor/overview.md

@@ -64,9 +64,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK.
-
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
+Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
 ## Code and database sources
 
@@ -173,9 +171,7 @@ Because stored agents are data, you can build automation loops that tune agents
 - Re-run the experiment against the draft and compare scores to the baseline.
 - Promote the draft to the published version when the scores improve.
 
-This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested.
-
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
+This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
 
 ## What can be overridden
 

package/.docs/docs/editor/prompts.md

@@ -122,7 +122,7 @@ await editor.agent.update({
 })
 ```
 
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
+See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
 
 ## Versioning
 

package/.docs/docs/editor/tools.md

@@ -52,7 +52,7 @@ Integration providers connect external tool platforms to the editor. Once regist
 
 [Composio](https://composio.dev) gives access to hundreds of integration tools organized into toolkits (GitHub, Slack, Gmail, and others).
 
-1. Get an API key from your Composio dashboard.
+1. Get a **project** API key (the `x-api-key` type) from your [Composio dashboard](https://dashboard.composio.dev).
 
 2. Register the provider in your Editor configuration:
 
@@ -75,7 +75,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    })
    ```
 
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to the `resourceId` passed through request context for per-user authentication.
+   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. By default, tool calls use the connection pinned by the agent's author. To route calls to each end user's own account instead, see [connection scope](https://mastra.ai/docs/agent-builder/integrations) in the Agent Builder docs.
 
 ### Arcade
 
@@ -142,9 +142,7 @@ When an agent runs, tools from all sources are merged in this order:
 2. Integration tools
 3. MCP tools
 
-If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description.
-
-> **Note:** See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
+If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description. See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
 
 ## Related
 

package/.docs/docs/evals/custom-scorers.md

@@ -341,9 +341,7 @@ A custom scorer in Mastra uses `createScorer` with four core components:
 3. [**Score Generation**](#score-generation)
 4. [**Reason Generation**](#reason-generation)
 
-Together, these components allow you to define custom evaluation logic using LLMs as judges.
-
-> **Info:** Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
+Together, these components allow you to define custom evaluation logic using LLMs as judges. Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'

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

@@ -6,6 +6,8 @@
 
 Datasets are collections of test cases that you run experiments against to measure how well your agents and workflows perform. Each mutation creates a new version, so you can reproduce past experiments exactly. Pair datasets with [scorers](https://mastra.ai/docs/evals/overview) to track quality across prompts, models, or code changes.
 
+**For AI agents:** Run `npx mastra api dataset create '{"name":"translation-pairs"}'` to create a dataset directly instead of opening Studio or writing a temporary script. The command requires a running Mastra server with a storage adapter that supports datasets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api dataset create --schema` before adding different dataset fields. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
+
 ## Usage
 
 ### Configure storage
@@ -41,7 +43,7 @@ const existing = await datasets.get({ id: 'dataset-id' })
 const { datasets: all } = await datasets.list()
 ```
 
-> **Info:** Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
+Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
 
 ## Studio
 
@@ -196,9 +198,7 @@ Fetch the exact items that existed at a past version:
 const items = await dataset.listItems({ version: 2 })
 ```
 
-You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments).
-
-> **Info:** Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
 ## Related
 

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

@@ -6,6 +6,8 @@
 
 An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. Results are persisted to storage so you can compare runs across different prompts, models, or code changes.
 
+**For AI agents:** Run `npx mastra api experiment run dataset_123 '{"name":"translation-baseline"}'` to start an experiment directly instead of opening Studio or writing a temporary script. Use a dataset ID returned by `npx mastra api dataset list` in place of the sample ID. The command requires a running Mastra server with dataset storage and registered experiment targets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api experiment run --schema` before constructing different input, and get user approval before starting an experiment because it can make model calls. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
+
 ## Basic experiment
 
 Call [`startExperiment()`](https://mastra.ai/reference/datasets/startExperiment) with a target and scorers:
@@ -127,7 +129,7 @@ for (const item of summary.results) {
 }
 ```
 
-> **Info:** Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
+Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
 ## Tool mocks
 
@@ -344,7 +346,7 @@ for (const result of results) {
 - `completedWithErrors` is `true` when the experiment finished but some items failed.
 - Items cancelled via `signal` appear in `skippedCount`.
 
-> **Info:** Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
+Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
 
 ## Related
 

package/.docs/docs/evals/evals-with-memory.md

@@ -136,9 +136,7 @@ const summary = await dataset.startExperiment({
 })
 ```
 
-The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer.
-
-> **Note:** Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
+The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer. Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
 
 ## Related
 

package/.docs/docs/evals/gates-and-verdicts.md

@@ -64,9 +64,24 @@ const result = await runEvals({
 // result.gateResults: [{ id: 'check-called-tool', passed: true, score: 1 }]
 ```
 
-Any scorer works as a gate. Quick Checks are a natural fit because they return binary 1/0 scores.
+Any scorer works as a gate. Quick Checks are a natural fit because they return binary 1/0 scores. Visit [runEvals() reference](https://mastra.ai/reference/evals/run-evals) for the full parameter and return type documentation.
 
-> **Note:** Visit [runEvals() reference](https://mastra.ai/reference/evals/run-evals) for the full parameter and return type documentation.
+### Gate-only runs
+
+`scorers` is optional when at least one gate is provided. This is useful for deterministic CI checks where you only care about pass/fail gates and don't need to track any quality metrics.
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+
+const result = await runEvals({
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  target: weatherAgent,
+  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
+})
+```
+
+You must provide at least one scorer or gate — a run with neither throws an error.
 
 ## Thresholds
 

package/.docs/docs/evals/quick-checks.md

@@ -127,9 +127,7 @@ Each check is a standard `createScorer()` instance with a `preprocess` step and
 1. **preprocess**: Extracts and normalizes relevant data from the agent run (text content, tool calls)
 2. **generateScore**: Converts the preprocessed result into a score (typically binary 1 or 0)
 
-Because checks skip the `analyze` and `generateReason` steps and make no LLM calls, they run in microseconds.
-
-> **Note:** Visit the [Quick Checks reference](https://mastra.ai/reference/evals/checks) for the full API, including all parameters and options for each check.
+Because checks skip the `analyze` and `generateReason` steps and make no LLM calls, they run in microseconds. Visit the [Quick Checks reference](https://mastra.ai/reference/evals/checks) for the full API, including all parameters and options for each check.
 
 ## Related