@mastra/mcp-docs-server 1.2.4-alpha.6 → 1.2.4-alpha.8

package/.docs/reference/core/getAgentById.md

@@ -2,22 +2,55 @@
 
 # Mastra.getAgentById()
 
-The `.getAgentById()` method is used to retrieve an agent by its ID. The method accepts a single `string` parameter for the agent's ID.
+The `.getAgentById()` method retrieves a registered agent by its `id`. It first searches registered agents by `agent.id`. If no agent matches, it falls back to [`Mastra.getAgent()`](https://mastra.ai/reference/core/getAgent) and treats the provided value as the agent registry key.
+
+Use `mastra.getAgentById(id)` to retrieve the code-defined agent. Use `await mastra.getAgentById(id, version)` to retrieve a versioned agent.
 
 ## Usage example
 
+The following example registers an agent, retrieves it by ID, and uses the returned agent.
+
 ```typescript
-mastra.getAgentById('test-agent-123')
+import { Agent } from '@mastra/core/agent'
+import { Mastra } from '@mastra/core/mastra'
+
+const supportAgent = new Agent({
+  id: 'support-agent-id',
+  name: 'Support Agent',
+  instructions: 'Answer support questions clearly and concisely.',
+  model: 'openai/gpt-5.5',
+})
+
+export const mastra = new Mastra({
+  agents: {
+    supportAgent,
+  },
+})
+
+const agent = mastra.getAgentById('support-agent-id')
+
+const response = await agent.generate('How can I reset my password?')
 ```
 
 ## Parameters
 
-**id** (`string`): The ID of the agent to retrieve. The method will first search for an agent with this ID, and if not found, will attempt to use it as a name to call getAgent().
+**id** (`string`): The ID of the agent to retrieve. Mastra first searches registered agents by \`agent.id\`. If none match, it uses this value as the agent registry key and calls \`getAgent()\`.
+
+**version** (`{ versionId: string } | { status?: 'draft' | 'published' }`): Optional version selector for retrieving a versioned agent. When provided, the method returns a promise.
+
+**version.versionId** (`string`): The ID of a specific agent version to retrieve.
+
+**version.status** (`'draft' | 'published'`): Select the latest agent version with this publication status.
 
 ## Returns
 
-**agent** (`Agent`): The agent instance with the specified ID. Throws an error if the agent is not found.
+**agent** (`TAgents[TAgentName]`): The agent instance with the specified ID when \`version\` is omitted.
+
+**agent** (`Promise<TAgents[TAgentName]>`): A promise that resolves to the versioned agent instance when \`version\` is provided.
+
+Throws a `MastraError` when no agent is found by ID or registry key.
 
 ## Related
 
+- [Mastra.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [Agents overview](https://mastra.ai/docs/agents/overview)

package/.docs/reference/datasets/listExperimentResults.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists individual item results for a specific experiment with pagination.
+Lists individual item results for a specific experiment with optional filters and pagination. Filters are applied at the storage layer.
 
 ## Usage example
 
@@ -23,6 +23,18 @@ const { results, pagination } = await dataset.listExperimentResults({
   perPage: 50,
 })
 
+// Restrict to results that still need review
+const { results: pending } = await dataset.listExperimentResults({
+  experimentId: 'exp-id',
+  status: 'needs-review',
+})
+
+// Restrict to results tied to a specific trace
+const { results: byTrace } = await dataset.listExperimentResults({
+  experimentId: 'exp-id',
+  traceId: 'trace-abc',
+})
+
 for (const result of results) {
   console.log(`Item ${result.itemId}: ${result.error ? 'FAILED' : 'OK'}`)
 }
@@ -32,6 +44,12 @@ for (const result of results) {
 
 **experimentId** (`string`): ID of the experiment to list results for.
 
+**traceId** (`string`): Restrict results to those linked to this trace ID.
+
+**status** (`'needs-review' | 'reviewed' | 'complete'`): Restrict results to this per-result review status.
+
+**filters** (`ExperimentTenancyFilters`): Multi-tenant scoping filters (\`organizationId\`, \`projectId\`). Forwarded to the storage layer.
+
 **page** (`number`): Page number. Defaults to \`0\`.
 
 **perPage** (`number`): Number of results per page. Defaults to \`20\`.

package/.docs/reference/datasets/listExperiments.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-Lists all experiments (runs) for this dataset with pagination.
+Lists experiments (runs) for this dataset with optional filters and pagination. Filters are applied at the storage layer, so results are always scoped to the current dataset.
 
 ## Usage example
 
@@ -17,8 +17,17 @@ const mastra = new Mastra({
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 
+// Basic pagination
 const { experiments, pagination } = await dataset.listExperiments({ page: 0, perPage: 10 })
 
+// Filter to a specific agent version — useful for baseline vs variant comparisons
+const { experiments: v2Runs } = await dataset.listExperiments({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  agentVersion: 'v2',
+  status: 'completed',
+})
+
 for (const exp of experiments) {
   console.log(`${exp.id}: ${exp.status} (${exp.succeededCount}/${exp.totalItems})`)
 }
@@ -26,6 +35,16 @@ for (const exp of experiments) {
 
 ## Parameters
 
+**targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Restrict results to experiments run against this target type.
+
+**targetId** (`string`): Restrict results to experiments run against this target ID.
+
+**agentVersion** (`string`): Restrict results to experiments recorded against this agent version. Useful for distinguishing baseline from variant runs.
+
+**status** (`'pending' | 'running' | 'completed' | 'failed'`): Restrict results to experiments in this status.
+
+**filters** (`ExperimentTenancyFilters`): Multi-tenant scoping filters (\`organizationId\`, \`projectId\`). Forwarded to the storage layer.
+
 **page** (`number`): Page number. Defaults to \`0\`.
 
 **perPage** (`number`): Number of experiments per page. Defaults to \`20\`.

package/.docs/reference/tools/create-tool.md

@@ -55,7 +55,13 @@ export const tool = createTool({
 
 **requestContextSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema for validating request context values. When provided, the context is validated before execute() runs, returning an error object if validation fails.
 
-**execute** (`function`): The function that contains the tool's logic. It receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing \`requestContext\`, \`tracingContext\`, \`abortSignal\`, and other execution metadata.
+**providerOptions** (`Record<string, Record<string, unknown>>`): Provider-specific options passed to the model when this tool is used. Keys are provider names, such as \`anthropic\` or \`openai\`, and values are provider-specific configuration objects.
+
+**inputExamples** (`Array<{ input: Record<string, unknown> }>`): Examples of valid tool inputs that supported model providers can use as input examples.
+
+**background** (`ToolBackgroundConfig`): Background task configuration for this tool. When enabled, the tool can execute in the background while the agent conversation continues.
+
+**execute** (`function`): The function that contains the tool's logic. Ordinary custom tools usually provide \`execute\`, but the type allows omission for tool definitions that are executed or adapted elsewhere. It receives two parameters: the validated input data based on inputSchema (first parameter) and an execution context object (second parameter) containing \`requestContext\`, \`abortSignal\`, and other execution metadata.
 
 **execute.input** (`z.infer<TInput>`): The validated input data based on inputSchema
 
@@ -63,8 +69,6 @@ export const tool = createTool({
 
 **execute.context.requestContext** (`RequestContext`): Request Context for accessing shared state and dependencies
 
-**execute.context.tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata
-
 **execute.context.abortSignal** (`AbortSignal`): Signal for aborting the tool execution
 
 **execute.context.agent** (`AgentToolExecutionContext`): Agent-specific context, available when the tool is executed by an agent.
@@ -75,13 +79,15 @@ export const tool = createTool({
 
 **execute.context.observe** (`ToolObserve`): Observability helpers for recording child spans and structured logs from inside a tool's execute function. Always provided — when no tracing context is active, \`span\` runs the function directly and \`log\` is a no-op.
 
-**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Signature: \`(options: ToolCallOptions) => void | PromiseLike\<void>\`.
+
+**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Signature: \`({ inputTextDelta, ...options }: { inputTextDelta: string } & ToolCallOptions) => void | PromiseLike\<void>\`.
 
-**onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Signature: \`({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>\`.
 
-**onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Receives the validated \`input\` object, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: \`({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>\`.
 
-**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Receives the tool's \`output\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.
+Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You do not need to configure them for ordinary `createTool()` usage.
 
 ## Returns
 
@@ -310,8 +316,9 @@ export const weatherTool = createTool({
     },
   },
   execute: async inputData => {
-    const weather = await fetchWeather(inputData.location)
-    return { weather }
+    return {
+      weather: `Current weather for ${inputData.location}: sunny`,
+    }
   },
 })
 ```
@@ -320,7 +327,44 @@ export const weatherTool = createTool({
 
 Tools support lifecycle hooks that allow you to monitor and react to different stages of tool execution. These hooks are particularly useful for logging, analytics, validation, and real-time updates during streaming.
 
-### Available Hooks
+The following example demonstrates a tool with all lifecycle hooks configured:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get weather for a city',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    city: z.string(),
+    forecast: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return {
+      city,
+      forecast: 'sunny',
+    }
+  },
+  onInputStart: ({ toolCallId }) => {
+    console.log(`Tool call ${toolCallId} input started`)
+  },
+  onInputDelta: ({ inputTextDelta, toolCallId }) => {
+    console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
+  },
+  onInputAvailable: ({ input, toolCallId }) => {
+    console.log(`Tool call ${toolCallId} received city: ${input.city}`)
+  },
+  onOutput: ({ output, toolCallId, toolName }) => {
+    console.log(`Tool ${toolName} call ${toolCallId} returned forecast: ${output.forecast}`)
+  },
+})
+```
+
+### Available hooks
 
 #### `onInputStart`
 
@@ -389,7 +433,7 @@ export const tool = createTool({
 })
 ```
 
-### Hook Execution Order
+### Hook execution order
 
 For a typical streaming tool call, the hooks are invoked in this order:
 
@@ -399,19 +443,14 @@ For a typical streaming tool call, the hooks are invoked in this order:
 4. Tool's **execute** function runs
 5. **onOutput**: Tool has completed successfully
 
-### Hook Parameters
-
-All hooks receive a parameter object with these common properties:
-
-- `toolCallId` (string): Unique identifier for this specific tool call
-- `abortSignal` (AbortSignal): Signal for detecting if the operation should be cancelled
+### Hook parameters
 
-Additionally:
+Hook callbacks receive these source-backed parameter shapes:
 
-- `onInputStart`, `onInputDelta`, and `onInputAvailable` receive `messages` (array): The conversation messages at the time of the tool call
-- `onInputDelta` receives `inputTextDelta` (string): The incremental text chunk
-- `onInputAvailable` receives `input`: The validated input data (typed according to `inputSchema`)
-- `onOutput` receives `output`: The tool's return value (typed according to `outputSchema`) and `toolName` (string): The name of the tool
+- `onInputStart`: Receives `ToolCallOptions`, including fields such as `toolCallId`, `messages`, and `abortSignal`.
+- `onInputDelta`: Receives `{ inputTextDelta: string } & ToolCallOptions`.
+- `onInputAvailable`: Receives `{ input: TSchemaIn } & ToolCallOptions`, where `input` is typed from `inputSchema`.
+- `onOutput`: Receives `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`, where `output` is typed from `outputSchema`. This hook does not receive `messages`.
 
 ### Error handling
 
@@ -430,7 +469,7 @@ mcp: {
 }
 ```
 
-### `ToolAnnotations` Properties
+### `ToolAnnotations` properties
 
 **title** (`string`): A human-readable title for the tool. Used for display purposes in UI components.
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.4-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`6a61846`](https://github.com/mastra-ai/mastra/commit/6a61846eeda29fb714549b70f1bee2bf6b141c44)]:
+  - @mastra/core@1.49.0-alpha.4
+
 ## 1.2.4-alpha.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.4-alpha.6",
+  "version": "1.2.4-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.49.0-alpha.3",
+    "@mastra/core": "1.49.0-alpha.4",
     "@mastra/mcp": "^1.13.0-alpha.1"
   },
   "devDependencies": {
@@ -47,7 +47,7 @@
     "vitest": "4.1.8",
     "@internal/lint": "0.0.110",
     "@internal/types-builder": "0.0.85",
-    "@mastra/core": "1.49.0-alpha.3"
+    "@mastra/core": "1.49.0-alpha.4"
   },
   "homepage": "https://mastra.ai",
   "repository": {