@mastra/mcp-docs-server 1.2.14-alpha.1 → 1.2.14-alpha.4

package/.docs/reference/agents/network.md

@@ -4,7 +4,7 @@
 
 The `.network()` method enables multi-agent collaboration and routing. This method accepts messages and optional execution options.
 
-> **Deprecated:** The `.network()` primitive has been deprecated and will be removed in a future major release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** The `.network()` primitive has been deprecated and will be removed in a future major release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 ## Usage example
 

package/.docs/reference/ai-sdk/handle-network-stream.md

@@ -2,7 +2,7 @@
 
 # handleNetworkStream()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Framework-agnostic handler for streaming network execution in AI SDK-compatible format. Use this function directly when you need to handle network streaming outside Hono or Mastra's own [apiRoutes](https://mastra.ai/docs/server/custom-api-routes) feature.
 

package/.docs/reference/ai-sdk/network-route.md

@@ -2,7 +2,7 @@
 
 # networkRoute()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Creates a network route handler for streaming network execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent network, and streams the response back to the client in AI SDK-compatible format. Agent networks allow a routing agent to delegate tasks to other agents. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
 

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

@@ -195,7 +195,7 @@ Invalid input is rejected before templates are fetched or files are created.
 
 **-l, --llm \<provider>** (`string`): Managed agent-harness provider: openai, anthropic, google, or xai.
 
-**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file.
+**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file when automatic provider setup succeeds.
 
 **--no-skills** (`boolean`): Skip automatic Mastra skills installation.
 

package/.docs/reference/client-js/workflows.md

@@ -212,6 +212,98 @@ A workflow run result yields the following:
 
 **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
 
+## Stored workflows
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+Stored workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for the definition format.
+
+### `listStoredWorkflows()`
+
+List stored workflow definitions, optionally filtered by `status` (`'active' | 'archived'`) and `authorId`:
+
+```typescript
+const { definitions, total } = await mastraClient.listStoredWorkflows({
+  status: 'active',
+})
+```
+
+### `upsertStoredWorkflow()`
+
+Create or replace a stored workflow definition. The server validates the definition, persists it, and live-registers it for execution:
+
+```typescript
+const stored = await mastraClient.upsertStoredWorkflow({
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+})
+```
+
+When the root definition nests helper workflows that don't exist yet, pass them in the same request through `dependencies`. The server validates and registers the bundle as a unit and echoes the helper ids back as `dependencyIds`:
+
+```typescript
+const stored = await mastraClient.upsertStoredWorkflow({
+  id: 'root-workflow',
+  // ...schemas and graph referencing 'helper-workflow'...
+  dependencies: [helperDefinition],
+})
+
+console.log(stored.dependencyIds) // ['helper-workflow']
+```
+
+### `getStoredWorkflow()`
+
+Get a stored workflow instance for definition management. To execute a stored workflow, use `getWorkflow(id).createRun()` like any other workflow:
+
+```typescript
+const storedWorkflow = mastraClient.getStoredWorkflow('greeting-workflow')
+```
+
+### `storedWorkflow.details()`
+
+Retrieve the persisted definition, including schemas, graph, status, and timestamps:
+
+```typescript
+const definition = await storedWorkflow.details()
+```
+
+### `storedWorkflow.delete()`
+
+Delete the stored definition and unregister the live workflow:
+
+```typescript
+await storedWorkflow.delete()
+```
+
+### Executing a stored workflow
+
+Once registered, a stored workflow runs through the ordinary workflow API:
+
+```typescript
+const workflow = mastraClient.getWorkflow('greeting-workflow')
+const run = await workflow.createRun()
+const result = await run.startAsync({ inputData: { name: 'Ada' } })
+```
+
 ## Schedules
 
 Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing workflow schedules at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).

package/.docs/reference/core/addStoredWorkflow.md

@@ -0,0 +1,62 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.addStoredWorkflow()
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+The `.addStoredWorkflow()` method validates a stored workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).
+
+See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup example and the [stored workflow definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) for the accepted fields and graph entries.
+
+## Usage example
+
+```typescript
+await mastra.addStoredWorkflow({
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+})
+
+const run = await mastra.getWorkflow('greeting-workflow').createRun()
+const result = await run.start({ inputData: { name: 'Ada' } })
+```
+
+## Parameters
+
+**def** (`StoredWorkflowGraph`): The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.
+
+## Returns
+
+A promise that resolves once the definition is validated, registered, and persisted.
+
+## Behavior
+
+- The definition is fully validated (structure, references, schema flow) before anything is mutated. Agents, tools, and workflows referenced by the graph must already be registered on the instance.
+- Adding a definition with an existing ID replaces both the stored definition and the live registration. In-flight runs keep the graph they started with.
+- Without a storage adapter that supports the `workflowDefinitions` domain, the workflow is still validated and registered in memory, but the definition is lost on restart.
+- To add a root workflow together with helper workflows it nests, use [`addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows).
+
+## Related
+
+- [Mastra.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows): Add a dependency-ordered bundle of definitions
+- [Mastra.getWorkflow()](https://mastra.ai/reference/core/getWorkflow): Retrieve a registered workflow
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
+- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries

package/.docs/reference/core/addStoredWorkflows.md

@@ -0,0 +1,40 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.addStoredWorkflows()
+
+> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+The `.addStoredWorkflows()` method adds a bundle of stored workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.
+
+The whole bundle is validated up front. Members are then registered in dependency order, so a helper is always in place before the workflow that nests it.
+
+[`addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow) is the single-member case.
+
+## Usage example
+
+```typescript
+await mastra.addStoredWorkflows([
+  helperDefinition, // nested by the root — order in the array doesn't matter
+  rootDefinition, // graph contains { type: 'workflow', workflowId: helperDefinition.id }
+])
+```
+
+## Parameters
+
+**defs** (`readonly StoredWorkflowGraph[]`): The workflow definitions to add. Nested-workflow references may resolve against the live registries or against other members of the same bundle.
+
+## Returns
+
+A promise that resolves once every member is validated, registered, and persisted.
+
+## Behavior
+
+- References resolve against the instance's registries union the bundle's own IDs, so a root may nest a helper introduced in the same call. Registration order is derived from the dependency graph, not the array order.
+- A rejected bundle registers nothing. Duplicate IDs, invalid members, and dependency cycles are detected before anything is mutated, and if registration or persistence fails partway, the in-memory registry is restored to its prior state.
+- Storage writes happen last. A storage-level failure mid-bundle can leave some rows written, but the registry is still rolled back and the orphaned rows are inert until the next boot.
+
+## Related
+
+- [Mastra.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow): Add a single definition
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
+- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries

package/.docs/reference/editor/versioning.md

@@ -54,7 +54,7 @@ See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agen
 
 ## Sub-agent versioning
 
-Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/agents/supervisor-agents) in request context. Define selectors at three levels:
+Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:
 
 1. `Mastra` instance `versions`: Defaults for every invocation
 2. Server request-body `versions`: Per-request values added to request context

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

@@ -111,5 +111,5 @@ The `reason` summarizes the result and lists each criterion with its verdict, so
 ## Related
 
 - [isTaskComplete on stream()](https://mastra.ai/reference/streaming/agents/stream)
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
 - [createScorer](https://mastra.ai/reference/evals/create-scorer)

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

@@ -4,7 +4,7 @@
 
 Mastra configures [observability](https://mastra.ai/docs/observability/overview) from an `observability.ts` file directly under `src/mastra/`. The file default-exports an `Observability` instance that sets up tracing, logging, metrics, and feedback for the project.
 
-Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see [Observability overview](https://mastra.ai/docs/observability/overview) and [Observability configuration](https://mastra.ai/docs/observability/config).
+Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see the [observability overview](https://mastra.ai/docs/observability/overview) and [observability configuration](https://mastra.ai/docs/observability/overview).
 
 ## Quickstart
 
@@ -25,7 +25,7 @@ export default new Observability({
 
 ## Observability and storage
 
-`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [Observability storage](https://mastra.ai/docs/observability/storage).
+`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [observability signal support](https://mastra.ai/docs/observability/overview).
 
 ## Precedence with code
 

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

@@ -23,7 +23,7 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Production backends
 
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
 
 ## Precedence with code
 

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

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

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

@@ -51,7 +51,7 @@ The file-based convention only controls where the tool lives and how it's regist
 - Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
 - Use `requireApproval` when a tool needs human confirmation before execution.
 
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/harness/agent-controller) for the approval flow.
 
 ## Runtime boundary
 

package/.docs/reference/index.md

@@ -83,6 +83,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)
+- [.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow)
+- [.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows)
 - [.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
 - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
@@ -364,8 +366,10 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/workers/overview)
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
+- [Stored Workflow Definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
 - [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
+- [.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)
 - [.branch()](https://mastra.ai/reference/workflows/workflow-methods/branch)
 - [.commit()](https://mastra.ai/reference/workflows/workflow-methods/commit)
 - [.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
@@ -377,6 +381,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.sleep()](https://mastra.ai/reference/workflows/workflow-methods/sleep)
 - [.sleepUntil()](https://mastra.ai/reference/workflows/workflow-methods/sleepUntil)
 - [.then()](https://mastra.ai/reference/workflows/workflow-methods/then)
+- [.tool()](https://mastra.ai/reference/workflows/workflow-methods/tool)
 - [.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel)
 - [.restart()](https://mastra.ai/reference/workflows/run-methods/restart)
 - [.resume()](https://mastra.ai/reference/workflows/run-methods/resume)

package/.docs/reference/observability/tracing/configuration.md

@@ -196,7 +196,7 @@ Shuts down all observability instances and clears the registry.
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Concepts and usage guide
 - [Sampling Strategies](https://mastra.ai/docs/observability/tracing/overview): Sampling configuration details
-- [Multi-Config Setup](https://mastra.ai/docs/observability/config): Using multiple configurations
+- [Multi-Config Setup](https://mastra.ai/docs/observability/overview): Using multiple configurations
 
 ### Reference
 

package/.docs/reference/observability/tracing/exporters/confident-ai.md

@@ -0,0 +1,138 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# DeepEvalExporter
+
+Sends Tracing data to [Confident AI](https://www.confident-ai.com/) for evaluation and observability. Exported by `@mastra/deepeval`, which builds on the DeepEval SDK.
+
+See [Confident AI exporter](https://mastra.ai/docs/observability/integrations/exporters/confident-ai) for setup and usage.
+
+## Constructor
+
+```typescript
+new DeepEvalExporter(config?: DeepEvalExporterConfig)
+```
+
+## `DeepEvalExporterConfig`
+
+```typescript
+interface DeepEvalExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  environment?: string
+  name?: string
+  tags?: string[]
+  metadata?: Record<string, any>
+  threadId?: string
+  userId?: string
+  testCaseId?: string
+  turnId?: string
+  metricCollection?: string
+  traceMetricCollection?: string
+  llmMetricCollection?: string
+  agentMetricCollection?: string
+  toolMetricCollectionMap?: Record<string, string>
+  prompt?: Prompt
+  debug?: boolean
+  traceCaptureSink?: (trace: Trace) => void
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+**apiKey** (`string`): Confident AI API key. Falls back to the CONFIDENT\_API\_KEY env var. The exporter disables itself when no key is found.
+
+**environment** (`string`): Trace environment. Falls back to CONFIDENT\_TRACE\_ENVIRONMENT, then 'development'.
+
+**name** (`string`): Trace name applied to every trace. Defaults to the Mastra serviceName.
+
+**tags** (`string[]`): Tags applied to every trace.
+
+**metadata** (`Record<string, any>`): Metadata applied to every trace.
+
+**threadId** (`string`): Thread ID applied to every trace. A threadId in the root span metadata overrides it per request.
+
+**userId** (`string`): User ID applied to every trace. A userId in the root span metadata overrides it per request.
+
+**testCaseId** (`string`): Test case ID applied to every trace. A testCaseId in the root span metadata overrides it per request.
+
+**turnId** (`string`): Turn ID applied to every trace. A turnId in the root span metadata overrides it per request.
+
+**metricCollection** (`string`): Trace-level metric collection.
+
+**traceMetricCollection** (`string`): Trace-level metric collection. Takes precedence over metricCollection.
+
+**llmMetricCollection** (`string`): Metric collection applied to LLM spans.
+
+**agentMetricCollection** (`string`): Metric collection applied to agent spans.
+
+**toolMetricCollectionMap** (`Record<string, string>`): Metric collection applied per tool name.
+
+**prompt** (`Prompt`): Confident AI managed prompt linkage attached to LLM spans.
+
+**debug** (`boolean`): Logs exporter configuration and export errors to the console.
+
+**traceCaptureSink** (`(trace: Trace) => void`): Receives completed traces locally instead of posting them to Confident AI. Use for offline evaluation.
+
+**logLevel** (`'debug' | 'info' | 'warn' | 'error'`): Logger level (default: 'info')
+
+## Methods
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Confident AI. Builds the trace tree from the Mastra span stream and posts the trace when the root span ends.
+
+### `flush`
+
+```typescript
+async flush(): Promise<void>
+```
+
+Waits for any in-flight trace posts to settle without shutting down the exporter.
+
+### `shutdown`
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Finalizes any open traces and flushes pending posts.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+// Reads from CONFIDENT_API_KEY, CONFIDENT_TRACE_ENVIRONMENT
+const exporter = new DeepEvalExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+const exporter = new DeepEvalExporter({
+  apiKey: process.env.CONFIDENT_API_KEY,
+  environment: 'production',
+})
+```
+
+## Span type mapping
+
+| Mastra span type                                                       | Confident AI span type |
+| ---------------------------------------------------------------------- | ---------------------- |
+| `AGENT_RUN`, `WORKFLOW_RUN`                                            | `AGENT`                |
+| `MODEL_GENERATION`                                                     | `LLM`                  |
+| `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `CLIENT_TOOL_CALL` | `TOOL`                 |
+| `RAG_EMBEDDING`, `RAG_VECTOR_OPERATION`                                | `RETRIEVER`            |
+| All other exported span types                                          | `CUSTOM`               |
+
+Event spans (for example `MODEL_CHUNK`) are dropped.

package/.docs/reference/observability/tracing/interfaces.md

@@ -396,6 +396,14 @@ interface ModelGenerationAttributes {
   /** Model provider (e.g., 'openai', 'anthropic') */
   provider?: string
 
+  /**
+   * Definitions of the tools made available to the model for this generation
+   * (name, description, and JSON-schema parameters), captured once per
+   * generation. Per-step tool names live on MODEL_INFERENCE spans as
+   * `availableTools`.
+   */
+  tools?: ModelToolDefinition[]
+
   /** Type of result/output this model call produced */
   resultType?: 'tool_selection' | 'response_generation' | 'reasoning' | 'planning'
 
@@ -429,6 +437,27 @@ interface ModelGenerationAttributes {
 }
 ```
 
+### `ModelToolDefinition`
+
+Serialized definition of one tool made available to the model, attached to `MODEL_GENERATION` spans so observability exporters can surface tool schemas.
+
+```typescript
+interface ModelToolDefinition {
+  /** Tool type: 'function' for standard tools, or the provider tool type (e.g. 'provider-defined') */
+  type: string
+
+  name: string
+
+  description?: string
+
+  /** JSON schema of the tool's input parameters (function tools) */
+  parameters?: Record<string, unknown>
+
+  /** Provider tool id (e.g. 'anthropic.web_search_20250305') for provider-defined tools */
+  id?: string
+}
+```
+
 ### `ModelStepAttributes`
 
 Model Step attributes - for a single model execution within a generation.