@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.25

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

@@ -31,6 +31,28 @@ console.log(`Average scores:`, result.scores)
 console.log(`Processed ${result.summary.totalItems} items`)
 ```
 
+### Multi-turn evaluation
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from './agents/weather-agent'
+
+const result = await runEvals({
+  target: weatherAgent,
+  data: [
+    {
+      inputs: [
+        'What is the weather in Brooklyn?',
+        'What about tomorrow?',
+        'Compare the two forecasts.',
+      ],
+    },
+  ],
+  scorers: [checks.calledTool('get_weather', { times: 2 }), checks.includes('Brooklyn')],
+})
+```
+
 ### With gates and thresholds
 
 ```typescript
@@ -60,7 +82,7 @@ result.thresholdResults // [{ id, passed, averageScore, threshold }]
 
 **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. When provided, scorers may be omitted.
 
-**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).
+**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). For multi-turn agent runs (inputs/turns), runEvals generates and injects the shared thread and a resource, so memory.thread is optional; provide memory.resource to reuse a specific resource.
 
 **concurrency** (`number`): Number of test cases to run concurrently. (Default: `1`)
 
@@ -68,7 +90,11 @@ result.thresholdResults // [{ id, passed, averageScore, threshold }]
 
 ## Data item structure
 
-**input** (`string | string[] | CoreMessage[] | any`): Input data for the target. For agents: messages or strings. For workflows: workflow input data.
+**input** (`string | string[] | CoreMessage[] | any`): Input data for the target. For agents: messages or strings. For workflows: workflow input data. Optional when inputs is provided.
+
+**inputs** (`(string | string[] | CoreMessage[] | any)[]`): Multi-turn inputs. Each entry is one turn (same shape as input) sent sequentially to the agent on the same thread. Scorers see the accumulated output from all turns. Only supported for Agent targets. When provided, input can be omitted. Mutually exclusive with turns.
+
+**turns** (`EvalTurn[]`): Multi-turn conversation with per-turn assertions. Each turn is an object { input, gates?, scorers? } sent sequentially on the same thread; its gates/scorers evaluate only that turn's input and output. Per-turn outcomes are reported in turnResults and folded into the overall verdict. Only supported for Agent targets. Mutually exclusive with input and inputs.
 
 **groundTruth** (`any`): Expected or reference output for comparison during scoring.
 
@@ -112,6 +138,18 @@ For workflows, use `WorkflowScorerConfig` to specify scorers at different levels
 
 **thresholdResults** (`ThresholdResult[]`): Per-threshold-scorer results averaged across all data items. Each entry has id, passed, averageScore, and threshold.
 
+**turnResults** (`TurnResult[]`): Present when any data item uses turns. Each entry has index (zero-based turn), optional gateResults, thresholdResults, and scores (bare-scorer averages keyed by scorer id), aggregated by turn index across data items.
+
+## EvalTurn
+
+A single turn in a `turns` array. Its `gates`/`scorers` evaluate only that turn's input and output:
+
+**input** (`string | string[] | CoreMessage[] | any`): The input sent to the agent for this turn.
+
+**gates** (`MastraScorer[]`): Gates that must score 1.0 for this turn. A failing turn gate makes the overall verdict failed.
+
+**scorers** (`ScorerEntry[]`): Scorers (optionally with thresholds) evaluated against this turn only. A missed per-turn threshold (with gates passing) makes the verdict scored.
+
 ## ScorerEntry
 
 A scorer entry in the `scorers` array can be either a bare scorer or a scorer with a threshold:
@@ -314,8 +352,62 @@ const result = await runEvals({
 })
 ```
 
+### Multi-turn conversation evaluation
+
+Use `inputs` to send sequential turns on a shared thread. Scorers see the accumulated output from all turns:
+
+```typescript
+const result = await runEvals({
+  target: chatAgent,
+  data: [
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  gates: [checks.calledTool('get_weather')],
+  scorers: [{ scorer: checks.similarity('Brooklyn weather forecast'), threshold: 0.5 }],
+})
+
+// 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.
+
+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
+
+Use `turns` to attach `gates`/`scorers` to individual turns. Each per-turn assertion sees only that turn's input and output, so a later-turn regression can't be hidden by an earlier turn:
+
+```typescript
+const result = await runEvals({
+  target: chatAgent,
+  data: [
+    {
+      turns: [
+        {
+          input: 'What is the weather in Brooklyn?',
+          gates: [checks.calledTool('get_weather')],
+        },
+        {
+          input: 'What about tomorrow?',
+          gates: [checks.calledTool('get_weather')], // must call again this turn
+          scorers: [{ scorer: checks.similarity('tomorrow forecast'), threshold: 0.5 }],
+        },
+      ],
+    },
+  ],
+})
+
+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`.
+
 ## Related
 
+- [Multi-turn evals](https://mastra.ai/docs/evals/multi-turn): Conceptual guide to multi-turn evaluation
 - [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

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

@@ -16,16 +16,17 @@ import { z } from 'zod'
 
 export default createTool({
   id: 'get_weather',
-  description: 'Get the current weather for a city.',
+  description: 'Get the current weather for a location.',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    tempC: z.number(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ context }) => {
-    return { city: context.city, tempC: 21 }
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```

package/.docs/reference/index.md

@@ -57,6 +57,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [WorkOS](https://mastra.ai/reference/auth/workos)
 - [AgentBrowser](https://mastra.ai/reference/browser/agent-browser)
 - [BrowserViewer](https://mastra.ai/reference/browser/browser-viewer)
+- [FirecrawlBrowser](https://mastra.ai/reference/browser/firecrawl-browser)
 - [MastraBrowser Class](https://mastra.ai/reference/browser/mastra-browser)
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
 - [ChannelProvider](https://mastra.ai/reference/channels/channel-provider)
@@ -142,6 +143,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Completeness](https://mastra.ai/reference/evals/completeness)
 - [Content Similarity Scorer](https://mastra.ai/reference/evals/content-similarity)
 - [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision)
+- [Context Recall Scorer](https://mastra.ai/reference/evals/context-recall)
 - [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance)
 - [Faithfulness](https://mastra.ai/reference/evals/faithfulness)
 - [Hallucination](https://mastra.ai/reference/evals/hallucination)
@@ -336,6 +338,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Inworld Realtime](https://mastra.ai/reference/voice/inworld-realtime)
 - [LiveKit](https://mastra.ai/reference/voice/livekit)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
+- [Mistral](https://mastra.ai/reference/voice/mistral)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)
 - [OpenAI Realtime](https://mastra.ai/reference/voice/openai-realtime)
@@ -392,6 +395,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
 - [MesaFilesystem](https://mastra.ai/reference/workspace/mesa-filesystem)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
+- [PlatformFilesystem](https://mastra.ai/reference/workspace/platform-filesystem)
+- [PlatformSandbox](https://mastra.ai/reference/workspace/platform-sandbox)
 - [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)

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

@@ -408,6 +408,27 @@ Setting `bufferTokens: false` disables both observation and reflection async buf
 
 Observational Memory emits typed data parts during agent execution that clients can use for real-time UI feedback. These are streamed alongside the agent's response.
 
+### Read extractor results
+
+Both completion events carry extractor output in their `data` payload. The extractor fields are:
+
+```typescript
+interface DataOmObservationEndPart {
+  type: 'data-om-observation-end'
+  data: {
+    /** Whether the completed work was an observation or reflection */
+    operationType: 'observation' | 'reflection'
+    /** Values extracted during this OM operation, keyed by extractor slug */
+    extractedValues?: Record<string, unknown>
+    /** Extractor failures from this OM operation. Successful extractor values are still included */
+    extractionFailures?: Array<{ slug: string; error: string }>
+    // ...other fields documented in the tables below
+  }
+}
+```
+
+Both extractor fields are optional. A completion can include values, failures, both, or neither. `data-om-observation-end` reports synchronous completion. `data-om-buffering-end` reports completed background work whose buffered content still awaits activation, although extractor metadata is already persisted. `DataOmBufferingEndPart` carries the same extractor fields, and both types are exported from `@mastra/memory/processors`. See [Read extracted values from a stream](https://mastra.ai/docs/memory/observational-memory) for a consumer example.
+
 ### `data-om-status`
 
 Emitted once per agent loop step, before model generation. Provides a snapshot of the current memory state, including token usage for both context windows and the state of any async buffered content.

package/.docs/reference/observability/tracing/exporters/posthog.md

@@ -39,6 +39,14 @@ async exportTracingEvent(event: TracingEvent): Promise<void>
 
 Exports a tracing event to PostHog.
 
+### `onFeedbackEvent`
+
+```typescript
+async onFeedbackEvent(event: FeedbackEvent): Promise<void>
+```
+
+Exports a feedback event to PostHog. See [Feedback export](#feedback-export).
+
 ### flush
 
 ```typescript
@@ -92,4 +100,34 @@ const exporter = new PosthogExporter({
 | `AGENT_RUN`          | `$ai_span`         |
 | `WORKFLOW_RUN`       | `$ai_span`         |
 | All other workflows  | `$ai_span`         |
-| `GENERIC`            | `$ai_span`         |
+| `GENERIC`            | `$ai_span`         |
+
+## Feedback export
+
+Feedback recorded with [`addFeedback()`](https://mastra.ai/docs/observability/feedback) is exported to PostHog as a native `$ai_feedback` event. PostHog shows it as **User feedback** on the linked trace. No extra configuration is needed.
+
+```typescript
+const trace = await mastra.observability.getRecordedTrace({ traceId })
+await trace.addFeedback({
+  feedbackType: 'thumbs',
+  value: 'down',
+  comment: 'Wrong answer',
+})
+```
+
+Feedback events map to these PostHog properties:
+
+| Mastra feedback field                  | PostHog property    |
+| -------------------------------------- | ------------------- |
+| `traceId`                              | `$ai_trace_id`      |
+| `comment` (or `value` when no comment) | `$ai_feedback_text` |
+| `feedbackId`                           | `feedback_id`       |
+| `feedbackType`                         | `feedback_type`     |
+| `value`                                | `feedback_value`    |
+| `feedbackSource`                       | `feedback_source`   |
+| `spanId`                               | `span_id`           |
+| `sourceId`                             | `source_id`         |
+| `metadata.sessionId`                   | `$ai_session_id`    |
+| `metadata` (other keys)                | custom properties   |
+
+Feedback without a `traceId` is dropped because PostHog anchors feedback to a trace through `$ai_trace_id`. The event's distinct ID resolves from `feedbackUserId`, then `metadata.userId`, then `defaultDistinctId`, then `anonymous`.

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -14,9 +14,7 @@ To opt out or customize the auto-applied filter, use the `sensitiveDataFilter` o
 import { Observability } from '@mastra/observability'
 
 new Observability({
-  configs: {
-    /* ... */
-  },
+  configs: {/* ... */},
   // disable the auto-applied filter
   sensitiveDataFilter: false,
   // or customize it

package/.docs/reference/processors/token-limiter-processor.md

@@ -85,9 +85,7 @@ export const agent = new Agent({
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
-  memory: new Memory({
-    /* ... */
-  }),
+  memory: new Memory({/* ... */}),
   inputProcessors: [
     new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
   ],

package/.docs/reference/rag/database-config.md

@@ -11,6 +11,7 @@ export type DatabaseConfig = {
   pinecone?: PineconeConfig
   pgvector?: PgVectorConfig
   chroma?: ChromaConfig
+  turbopuffer?: TurbopufferConfig
   [key: string]: any // Extensible for future databases
 }
 ```
@@ -90,6 +91,17 @@ whereDocument: { "$contains": "API documentation" }
 - Content-based document filtering
 - Complex query combinations
 
+### `TurbopufferConfig`
+
+Configuration options specific to Turbopuffer vector store.
+
+**consistency** (`'strong' | 'eventual'`): The consistency level for queries. "strong" (default) guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet.
+
+**Use Cases:**
+
+- Latency-sensitive queries where slightly stale data is acceptable (`eventual`)
+- Read-your-writes workflows that must see the latest data (`strong`)
+
 ## Usage examples
 
 **Basic Usage**:

package/.docs/reference/streaming/agents/stream.md

@@ -100,7 +100,7 @@ const stream = await agent.stream('message for agent')
 
 **options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
 
-**options.structuredOutput.jsonPromptInjection** (`boolean`): Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.
+**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 
 **options.structuredOutput.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } }).
 
@@ -124,6 +124,8 @@ const stream = await agent.stream('message for agent')
 
 **options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, workingMemory, and filterIncompleteToolCalls.
 
+**options.memory.onTitleGenerated** (`(title: string) => void | Promise<void>`): Callback fired asynchronously when a thread title is generated and persisted to storage. Title generation runs in the background and may complete after the stream ends. Only fires when generateTitle is enabled in memory options and the thread has no existing title.
+
 **options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
 
 **options.onStepFinish** (`StreamTextOnStepFinishCallback<any> | never`): Callback function called after each execution step. Receives step details as a JSON string. Unavailable for structured output

package/.docs/reference/templates/overview.md

@@ -30,28 +30,28 @@ Install a template using the `create-mastra` command:
 **npm**:
 
 ```sh
-npx create-mastra@latest --template template-name
+npx create-mastra@latest my-project --template template-name
 ```
 
 **pnpm**:
 
 ```sh
-pnpm dlx create-mastra@latest --template template-name
+pnpm dlx create-mastra@latest my-project --template template-name
 ```
 
 **Yarn**:
 
 ```sh
-yarn dlx create-mastra@latest --template template-name
+yarn dlx create-mastra@latest my-project --template template-name
 ```
 
 **Bun**:
 
 ```sh
-bun x create-mastra@latest --template template-name
+bun x create-mastra@latest my-project --template template-name
 ```
 
-This creates a complete project with all necessary code and configuration.
+This creates a complete project and installs its dependencies. The template author controls the models, provider dependencies, environment variables, and source code.
 
 ### Setup Process
 
@@ -71,33 +71,7 @@ After installation:
 
    Edit `.env` with required API keys as documented in the template's README.
 
-3. **Install dependencies** (if not done automatically):
-
-   **npm**:
-
-   ```sh
-   npm install
-   ```
-
-   **pnpm**:
-
-   ```sh
-   pnpm install
-   ```
-
-   **Yarn**:
-
-   ```sh
-   yarn install
-   ```
-
-   **Bun**:
-
-   ```sh
-   bun install
-   ```
-
-4. **Start development server**:
+3. **Start development server**:
 
    **npm**:
 

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

@@ -10,25 +10,29 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-export const tool = createTool({
-  id: 'test-tool',
-  description: 'Reverse the input string',
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    input: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    const reversed = inputData.input.split('').reverse().join('')
-
+  execute: async ({ location }) => {
     return {
-      output: reversed,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
+The first `execute` parameter is the validated value from `inputSchema`. Destructure schema fields directly in the function signature, as shown with `{ location }`. The optional second parameter contains the execution context.
+
 ## Parameters
 
 **id** (`string`): A unique identifier for the tool.
@@ -112,10 +116,12 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -137,11 +143,13 @@ export const weatherTool = createTool({
   ),
   outputSchema: toStandardJsonSchema(
     v.object({
-      weather: v.string(),
+      location: v.string(),
+      temperatureCelsius: v.number(),
+      conditions: v.string(),
     }),
   ),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -159,10 +167,12 @@ export const weatherTool = createTool({
     location: 'string',
   }),
   outputSchema: type({
-    weather: 'string',
+    location: 'string',
+    temperatureCelsius: 'number',
+    conditions: 'string',
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -176,18 +186,22 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   strict: true,
   inputSchema: z.object({
-    city: z.string(),
-    units: z.enum(['metric', 'imperial']),
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city, units }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      units,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -204,28 +218,31 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    temperature: z.number(),
-    condition: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
     radarImageUrl: z.string().url(),
   }),
-  execute: async ({ city }) => ({
-    city,
-    temperature: 72,
-    condition: 'sunny',
+  execute: async ({ location }) => ({
+    location,
+    temperatureCelsius: 21,
+    conditions: 'sunny',
     radarImageUrl: 'https://example.com/radar/seattle.png',
   }),
   toModelOutput: output => {
     return {
       type: 'content',
       value: [
-        { type: 'text', text: `${output.city}: ${output.temperature}F and ${output.condition}` },
+        {
+          type: 'text',
+          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
+        },
         { type: 'image-url', url: output.radarImageUrl },
       ],
     }
@@ -294,11 +311,16 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get current weather for a location',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
     location: z.string().describe('City name or coordinates'),
   }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
+  }),
   // MCP-specific properties
   mcp: {
     // Annotations for client behavior hints
@@ -315,9 +337,11 @@ export const weatherTool = createTool({
       category: 'weather',
     },
   },
-  execute: async inputData => {
+  execute: async ({ location }) => {
     return {
-      weather: `Current weather for ${inputData.location}: sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -334,19 +358,21 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    forecast: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
   onInputStart: ({ toolCallId }) => {
@@ -356,10 +382,10 @@ export const weatherTool = createTool({
     console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
   },
   onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Tool call ${toolCallId} received city: ${input.city}`)
+    console.log(`Tool call ${toolCallId} received location: ${input.location}`)
   },
   onOutput: ({ output, toolCallId, toolName }) => {
-    console.log(`Tool ${toolName} call ${toolCallId} returned forecast: ${output.forecast}`)
+    console.log(`Tool ${toolName} call ${toolCallId} returned conditions: ${output.conditions}`)
   },
 })
 ```
@@ -403,7 +429,7 @@ export const tool = createTool({
   id: 'example-tool',
   description: 'Example tool with hooks',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
     console.log(`Tool received complete input:`, input)