@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/{(docs)/guides → guides}/suggestions.mdx

@@ -1,6 +1,7 @@
 ---
 title: Suggestions
 description: Display suggested prompts to help users get started with your assistant.
+platforms: ["react"]
 ---
 
 Suggestions are pre-defined prompts that help users discover what your assistant can do. They appear in the welcome screen and provide a quick way to start conversations.
@@ -85,7 +86,7 @@ The default Thread component from the shadcn registry already includes suggestio
 
 ### Customizing Suggestion Display
 
-If you want to customize how suggestions are displayed, you can modify your Thread component:
+If you want to customize how suggestions are displayed, you can modify your Thread component. The idiomatic pattern is to wrap the suggestions in `AuiIf` so they only appear when the thread is empty:
 
 ```tsx
 import {
@@ -96,17 +97,18 @@ import {
 
 const ThreadWelcome = () => {
   return (
-    <div className="flex flex-col items-center justify-center">
-      <h1>Welcome!</h1>
-      <p>How can I help you today?</p>
-
-      {/* Display suggestions */}
-      <div className="grid grid-cols-2 gap-2">
-        <ThreadPrimitive.Suggestions>
-          {() => <SuggestionItem />}
-        </ThreadPrimitive.Suggestions>
+    <AuiIf condition={(s) => s.thread.isEmpty}>
+      <div className="flex flex-col items-center justify-center">
+        <h1>Welcome!</h1>
+        <p>How can I help you today?</p>
+
+        <div className="grid grid-cols-2 gap-2">
+          <ThreadPrimitive.Suggestions>
+            {() => <SuggestionItem />}
+          </ThreadPrimitive.Suggestions>
+        </div>
       </div>
-    </div>
+    </AuiIf>
   );
 };
 
@@ -126,53 +128,13 @@ const SuggestionItem = () => {
 };
 ```
 
-## Suggestion Primitives
-
-### ThreadPrimitive.Suggestions
-
-Renders all suggestions from the suggestions scope.
-
-```tsx
-<ThreadPrimitive.Suggestions>
-  {() => <CustomSuggestionComponent />}
-</ThreadPrimitive.Suggestions>
-```
-
-### SuggestionPrimitive.Title
-
-Displays the suggestion's title (the first part when using object format, or the full text when using strings).
-
-```tsx
-<SuggestionPrimitive.Title />
-```
-
-### SuggestionPrimitive.Description
+### Dismissal
 
-Displays the suggestion's description/label (only shown when using object format).
+Suggestions dismiss automatically once the user sends a message because `thread.isEmpty` becomes false. No extra state management is needed. If you want to dismiss suggestions without sending (for example, after a user clicks away), manage a local boolean and combine it with the `AuiIf` condition or a plain conditional render.
 
-```tsx
-<SuggestionPrimitive.Description />
-```
-
-### SuggestionPrimitive.Trigger
-
-A button that triggers the suggestion action when clicked.
-
-```tsx
-<SuggestionPrimitive.Trigger
-  send={true}
-  clearComposer={true}
-  asChild
->
-  <button>Click me</button>
-</SuggestionPrimitive.Trigger>
-```
-
-**Props:**
+## Suggestion Primitives
 
-- `send` (boolean): When true, automatically sends the message. When false, only populates the composer.
-- `clearComposer` (boolean, default: true): When `send` is false, determines if the composer is cleared before adding the suggestion (true) or if the suggestion is appended (false).
-- `asChild` (boolean): Merge props with child element instead of rendering a button.
+The primitives available for rendering suggestions are `ThreadPrimitive.Suggestions`, `ThreadPrimitive.SuggestionByIndex`, `SuggestionPrimitive.Title`, `SuggestionPrimitive.Description`, and `SuggestionPrimitive.Trigger`. `ThreadPrimitive.SuggestionByIndex` is useful when you need layout control over a specific suggestion slot rather than iterating all of them. For the full prop reference and usage patterns, see the [Suggestion primitive docs](/docs/primitives/suggestion).
 
 ## Dynamic Suggestions
 
@@ -213,30 +175,6 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Context-Aware Suggestions
-
-Suggestions can be tailored to different contexts or user intents:
-
-```tsx
-const suggestions = [
-  {
-    title: "Code Review",
-    label: "Get feedback on your code",
-    prompt: "Can you review this code for me?",
-  },
-  {
-    title: "Debug Help",
-    label: "Find and fix issues",
-    prompt: "Help me debug this error",
-  },
-  {
-    title: "Best Practices",
-    label: "Learn recommended patterns",
-    prompt: "What are the best practices for this?",
-  },
-];
-```
-
 ## Best Practices
 
 1. **Keep suggestions concise**: Use clear, actionable prompts that users can understand at a glance
@@ -246,11 +184,11 @@ const suggestions = [
 5. **Limit the number**: 3-6 suggestions work best to avoid overwhelming users
 6. **Make them actionable**: Each suggestion should lead to a meaningful interaction
 
-## Migration from Legacy API
+## Switching from `ThreadPrimitive.Suggestion`
 
-If you're using the deprecated `ThreadPrimitive.Suggestion` component, migrate to the new API:
+If your codebase uses the inline `ThreadPrimitive.Suggestion` component (which renders one suggestion at a time with hardcoded `prompt` / `send` props), you can move to the runtime-driven `Suggestions()` API for centralized configuration. The inline component is still supported, but the runtime-driven approach scales better when suggestions need to update dynamically.
 
-### Before (Deprecated)
+### Inline form
 
 ```tsx
 <ThreadPrimitive.Suggestion
@@ -259,7 +197,7 @@ If you're using the deprecated `ThreadPrimitive.Suggestion` component, migrate t
 />
 ```
 
-### After (Recommended)
+### Runtime-driven form
 
 1. Configure suggestions in your runtime provider:
 

package/.docs/raw/docs/{(docs)/guides → guides}/tool-ui.mdx

@@ -1,6 +1,7 @@
 ---
 title: Generative UI
 description: Render tool calls as interactive UI instead of plain text.
+platforms: ["react"]
 ---
 
 import { ToolUISample } from "@/components/docs/samples/tool-ui";
@@ -26,7 +27,7 @@ There are two main approaches to creating tool UIs in assistant-ui:
 
 ### 1. Client-Defined Tools (`makeAssistantTool`)
 
-If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`:
+If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`. This component-based API coexists with the [Tools()](/docs/guides/tools) toolkit API; pick whichever fits your codebase better.
 
 ```tsx
 import { makeAssistantTool, tool } from "@assistant-ui/react";
@@ -503,44 +504,97 @@ render: ({ status, args }) => {
 };
 ```
 
-### Field-Level Validation
+### Deferred Rendering
 
-<Callout type="warn">
-  `useToolArgsFieldStatus` is not currently exported from `@assistant-ui/react`.
-  The hook exists internally but is not part of the public API. This section is
-  included for reference and may become available in a future release.
+<Callout type="info">
+This section applies when the model **drives** the component through a tool call (args arrive incrementally and you want to wait for the final shape). If your backend or orchestrator pushes the component instead, prefer [Data-Part Generative UI](#data-part-generative-ui) with `makeAssistantDataUI`. Data parts arrive as terminal events, so the renderer only fires once with the final data, no deferred rendering needed.
 </Callout>
 
-Use `useToolArgsFieldStatus` to show validation states:
+Sometimes you want to capture a tool call's streaming arguments but only render the final UI once the call completes. This is useful when partial args would render misleading or jarring intermediate states (a chart that flashes through half-populated data), when the component is expensive to mount (heavy visualizations, embedded iframes, third-party widgets), or when the model controls *whether* the component appears at all.
+
+#### Inline at the end of streaming
+
+Return `null` from the tool UI's `render` until `status.type === "complete"`. The streaming args still arrive in `args` as the model emits them, you just ignore them until the call is done:
+
+```tsx
+const ChartToolUI = makeAssistantToolUI<
+  { title: string; series: number[] },
+  void
+>({
+  toolName: "renderChart",
+  render: ({ args, status }) => {
+    if (status.type !== "complete") return null;
+    return <Chart title={args.title} data={args.series} />;
+  },
+});
+```
+
+The chart mounts once, with the final args, after streaming finishes. No re-renders during the stream.
+
+The same `render` shape works inside the [`Tools()`](/docs/guides/tools) toolkit's `render` field, with `useAssistantToolUI`, and with `MessagePrimitive.Parts`'s inline `tools.by_name` overrides. The deferred-rendering pattern applies regardless of how you registered the tool UI.
+
+#### Below the message body
+
+If the component should sit *outside* the message parts (for example, a card attached under the avatar block rather than inline with text), gate at the message level with [`AuiIf`](/docs/api-reference/primitives/assistant-if) and read `s.message.status`:
 
 ```tsx
-import { useToolArgsFieldStatus } from "@assistant-ui/react";
+import { MessagePrimitive, AuiIf, useAuiState } from "@assistant-ui/react";
+
+function PostMessageCard() {
+  const parts = useAuiState((s) => s.message.parts);
+  const chartCall = parts.find(
+    (p) => p.type === "tool-call" && p.toolName === "renderChart",
+  );
+  if (!chartCall) return null;
+  return <Chart {...chartCall.args} />;
+}
+
+<MessagePrimitive.Root>
+  <MessagePrimitive.Parts />
+
+  <AuiIf
+    condition={(s) =>
+      s.message.role === "assistant" &&
+      s.message.status?.type === "complete"
+    }
+  >
+    <PostMessageCard />
+  </AuiIf>
+</MessagePrimitive.Root>;
+```
+
+The `AuiIf` predicate fires whenever the assistant state changes; children mount only when both checks pass. `PostMessageCard` then reads the captured tool-call part from `s.message.parts` and renders from its args.
+
+For the opposite pattern (showing partial data as it streams in), see [Field-Level Streaming State](#field-level-streaming-state) and [Partial Results & Streaming](#partial-results--streaming) below.
+
+### Field-Level Streaming State
+
+Use `useToolArgsStatus` to react to per-field streaming state. The hook returns a `propStatus` map where each top-level key in the args object resolves from `"streaming"` to `"complete"` as the partial JSON arrives. Call it inside a tool-call message part context:
 
-const FormToolUI = makeAssistantToolUI({
+```tsx
+import { useToolArgsStatus } from "@assistant-ui/react";
+
+const FormToolUI = makeAssistantToolUI<{ email: string; phone: string }, unknown>({
   toolName: "submitForm",
   render: ({ args }) => {
-    const emailStatus = useToolArgsFieldStatus(["email"]);
-    const phoneStatus = useToolArgsFieldStatus(["phone"]);
+    const { propStatus } = useToolArgsStatus<{ email: string; phone: string }>();
 
     return (
       <form className="space-y-4">
         <div>
           <input
             type="email"
-            value={args.email}
-            className={emailStatus.type === "running" ? "loading" : ""}
+            value={args.email ?? ""}
+            className={propStatus.email === "streaming" ? "loading" : ""}
             disabled
           />
-          {emailStatus.type === "incomplete" && (
-            <span className="text-red-500">Invalid email</span>
-          )}
         </div>
 
         <div>
           <input
             type="tel"
-            value={args.phone}
-            className={phoneStatus.type === "running" ? "loading" : ""}
+            value={args.phone ?? ""}
+            className={propStatus.phone === "streaming" ? "loading" : ""}
             disabled
           />
         </div>
@@ -596,24 +650,7 @@ const AnalysisToolUI = makeAssistantToolUI<
 
 ### Custom Tool Fallback
 
-Provide a custom UI for tools without specific UIs:
-
-```tsx
-<Thread
-  components={{
-    ToolFallback: ({ toolName, args, result }) => (
-      <div className="tool-fallback rounded bg-gray-100 p-3">
-        <code className="text-sm">
-          {toolName}({JSON.stringify(args)})
-        </code>
-        {result && (
-          <pre className="mt-2 text-xs">{JSON.stringify(result, null, 2)}</pre>
-        )}
-      </div>
-    ),
-  }}
-/>
-```
+For tools that have no dedicated UI, add the `ToolFallback` shadcn component to your project. See the [ToolFallback install guide](/docs/ui/tool-fallback) for setup instructions and the [ToolGroup guide](/docs/ui/tool-group) for grouping consecutive tool calls into a collapsible container.
 
 ## Execution Context
 
@@ -777,6 +814,41 @@ const WeatherUI = makeAssistantToolUI({
 
 `propStatus` maps each key to `"streaming"` | `"complete"` once the key appears in the partial JSON. Keys not yet present in the stream are absent from `propStatus`.
 
+## Data-Part Generative UI
+
+Alongside tool-call rendering, assistant-ui supports a second generative UI mechanism based on `DataMessagePart`. Instead of attaching UI to a tool invocation, the backend (or the LangGraph graph) emits named data events that are appended as `{ type: "data", name, data }` parts on the parent assistant message.
+
+**When to choose which:**
+
+- **Tool UI**: the **model** decides what to render by calling a tool whose args become the component's data. Register the renderer via the [`Tools()`](/docs/guides/tools) toolkit's `render` field (recommended), or standalone with `makeAssistantToolUI` / `useAssistantToolUI` when the tool itself is defined elsewhere (backend, MCP, LangGraph). Args stream incrementally, so you observe partial state via `status` / `useToolArgsStatus` and may need [Deferred Rendering](#deferred-rendering) for components that should only mount with final data.
+- **Data UI** (`makeAssistantDataUI`): the **backend or orchestrator** decides what to render and pushes a named data event onto the assistant message. Data parts arrive as terminal events with no streaming partials, so the renderer naturally fires once with the final data.
+
+If you want a component to appear only after the message is complete and you control the backend, Data UI is usually the more direct fit; reach for Tool UI's deferred pattern when the model itself must drive the choice.
+
+Use `makeAssistantDataUI` to register a renderer for a named data part:
+
+```tsx
+import { makeAssistantDataUI } from "@assistant-ui/react";
+
+type ChartProps = { series: number[]; title: string };
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <div>
+      <h3>{data.title}</h3>
+      <Chart series={data.series} />
+    </div>
+  ),
+});
+```
+
+Mount `<ChartUI />` once inside the `AssistantRuntimeProvider` tree; it renders nothing itself and only registers the renderer.
+
+For LangGraph-specific patterns (emitting UI from a Python/TypeScript graph node via `push_ui_message` / `typedUi`, dynamic loading with `LoadExternalComponent`, and the `useLangGraphUIMessages` escape hatch), see [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui).
+
+A fallback renderer for unmatched data parts is available internally but `setFallbackDataUI` is not yet a public API.
+
 ## Related Guides
 
 - [Tools Guide](/docs/guides/tools) - Learn how to create and use tools with AI models

package/.docs/raw/docs/{(docs)/guides → guides}/tools.mdx

@@ -1,6 +1,7 @@
 ---
 title: Tools
 description: Give your assistant actions like API calls, database queries, and more.
+platforms: ["react"]
 ---
 
 Tools enable LLMs to take actions and interact with external systems. assistant-ui provides a comprehensive toolkit for creating, managing, and visualizing tool interactions in real-time.
@@ -24,9 +25,9 @@ When tools are executed, you can display custom generative UI components that pr
   creating your own Tool UI component for the tool's name.
 </Callout>
 
-## Recommended: Tools() API
+## Tools() API
 
-The `Tools()` API is the recommended way to register tools in assistant-ui. It provides centralized tool registration that prevents duplicate registrations and works seamlessly with all runtimes.
+The `Tools()` API is the recommended starting point for registering tools in assistant-ui. It provides centralized tool registration that prevents duplicate registrations and works seamlessly with all runtimes. For tools whose availability depends on a specific part of your UI being mounted, see the [component-based APIs](#component-based-apis) below; both styles are supported and can be mixed in the same app.
 
 ### Quick Start
 
@@ -207,6 +208,32 @@ execute: async (args, context) => {
 };
 ```
 
+### Cancellation
+
+`context.abortSignal` is an `AbortSignal` that fires when the user stops the run. Pass it to any async I/O so the work stops immediately:
+
+```tsx
+execute: async ({ query }, { abortSignal }) => {
+  const res = await fetch(`/api/search?q=${query}`, { signal: abortSignal });
+  return res.json();
+},
+```
+
+When using LangGraph with `unstable_createLangGraphStream`, the default `onDisconnect` value is already `"cancel"`, which tells the LangGraph server to cancel the run on abort:
+
+```ts
+import { unstable_createLangGraphStream } from "@assistant-ui/react-langgraph";
+
+const stream = unstable_createLangGraphStream({
+  client,
+  assistantId,
+  // onDisconnect defaults to "cancel"; the server cancels the run when the
+  // client disconnects or the user stops the message.
+});
+```
+
+See the [LangGraph quickstart](/docs/runtimes/langgraph/quickstart) for full setup.
+
 ### Human-in-the-Loop
 
 Tools can pause execution to request user input or approval:
@@ -260,15 +287,51 @@ const confirmationToolkit: Toolkit = {
 };
 ```
 
-## Alternative Methods (Legacy)
+### Streaming Tool Args
+
+While a tool is running, its arguments arrive as partial JSON. Use `useToolArgsStatus` inside a tool UI render function to react to each top-level field as it streams in. The hook is exported from `@assistant-ui/react`.
+
+```tsx
+import { useToolArgsStatus } from "@assistant-ui/react";
+
+const SearchToolUI = makeAssistantToolUI<{ query: string; limit: number }, unknown>({
+  toolName: "search",
+  render: ({ args }) => {
+    const { propStatus } = useToolArgsStatus<{ query: string; limit: number }>();
+
+    return (
+      <div>
+        <span className={propStatus.query === "streaming" ? "animate-pulse" : ""}>
+          {args.query ?? "..."}
+        </span>
+        {propStatus.limit === "complete" && <span> (limit: {args.limit})</span>}
+      </div>
+    );
+  },
+});
+```
+
+`propStatus` maps each top-level key in the args object to `"streaming"` while it is still being parsed and to `"complete"` once that field is fully present.
+
+## Component-Based APIs
+
+`makeAssistantTool`, `useAssistantTool`, and `makeAssistantToolUI` are component-and-hook-based APIs that coexist with the [`Tools()`](#tools-api) toolkit pattern. They are fully supported and the natural fit for the [intelligent components](/docs/copilots/motivation) pattern, where each part of your UI registers the tools it owns when it is mounted, for example a product-specific tool that should only be exposed while that product's screen is open.
+
+<Callout type="info">
+  Be careful not to register the same tool from both APIs at once: each API
+  registers under `toolName`, and duplicate registrations will be rejected.
+</Callout>
 
-<Callout type="warning">
-  The following methods are supported for backwards compatibility but are not
-  recommended for new code. They can cause duplicate registration errors and are
-  harder to maintain. Use the `Tools()` API instead.
+<Callout type="warn">
+  Tool **execution** can be registered dynamically (when a component mounts),
+  but tool **UI** should generally be pre-registered. A `render` function that
+  is only registered while a specific component is mounted will not render
+  when chat history is replayed or during server-side rendering. Either
+  declare the tool's `render` in a `Tools()` toolkit, or mount
+  `makeAssistantToolUI` near the root of your tree.
 </Callout>
 
-### Using `makeAssistantTool` (Deprecated)
+### Using `makeAssistantTool`
 
 Register tools with the assistant context. Returns a React component that registers the tool when rendered:
 
@@ -303,9 +366,9 @@ function App() {
 }
 ```
 
-**Why this is deprecated**: Component-based registration can lead to duplicate registrations if components are remounted or if the same tool is defined in multiple places.
+Tradeoff: component-based registration is tied to React lifecycle, so the tool is registered when the component mounts and unregistered when it unmounts. Take care not to remount it accidentally if you also register the same tool elsewhere.
 
-### Using `useAssistantTool` Hook (Deprecated)
+### Using the `useAssistantTool` Hook
 
 Register tools dynamically using React hooks:
 
@@ -329,9 +392,9 @@ function DynamicTools() {
 }
 ```
 
-**Why this is deprecated**: Hook-based registration ties tool definitions to component lifecycle, making them harder to test and potentially causing duplicate registrations.
+Tradeoff: like `makeAssistantTool`, the registration follows the component lifecycle. Useful for dynamic tools that depend on component state or props.
 
-### Using `makeAssistantToolUI` (Deprecated)
+### Using `makeAssistantToolUI`
 
 Create UI-only components for tools defined elsewhere:
 
@@ -365,7 +428,7 @@ function App() {
 }
 ```
 
-**Why this is deprecated**: Component-based UI registration can cause issues with tool UI not appearing or appearing multiple times.
+Tradeoff: like the other component-based APIs, the UI is registered while the component is mounted. Useful when the tool UI needs access to surrounding component state or context.
 
 ## Tool Paradigms
 
@@ -391,37 +454,32 @@ const frontendToolkit: Toolkit = {
 
 ### Backend Tools
 
-Tools executed server-side:
+Tools executed server-side live in your API route. A minimal example with the AI SDK:
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, tool, zodSchema } from "ai";
+import { z } from "zod";
 
-```tsx
-// Backend route (AI SDK)
 export async function POST(req: Request) {
   const { messages } = await req.json();
-
   const result = streamText({
     model: openai("gpt-4o"),
     messages: await convertToModelMessages(messages),
     tools: {
-      queryDatabase: {
+      queryDatabase: tool({
         description: "Query the application database",
-        inputSchema: zodSchema(
-          z.object({
-            query: z.string(),
-            table: z.string(),
-          }),
-        ),
-        execute: async ({ query, table }) => {
-          const results = await db.query(query, { table });
-          return results;
-        },
-      },
+        inputSchema: zodSchema(z.object({ query: z.string(), table: z.string() })),
+        execute: async ({ query, table }) => db.query(query, { table }),
+      }),
     },
   });
-
   return result.toUIMessageStreamResponse();
 }
 ```
 
+For the full AI SDK v6 backend setup including multi-step tool calls, frontend tools, history persistence with `withFormat`, and more, see the [AI SDK v6 guide](/docs/runtimes/ai-sdk/v6).
+
 ### Client-Defined Tools with frontendTools
 
 The Vercel AI SDK adapter implements automatic serialization of client-defined tools. Tools registered via the `Tools()` API are automatically included in API requests:
@@ -512,9 +570,47 @@ export async function POST(req: Request) {
 }
 ```
 
+## LangGraph subgraph events
+
+When a LangGraph graph contains sub-agents (nested subgraphs), events from those subgraphs arrive with a `metadata.namespace` field identifying the originating subgraph. Pass event handlers to `useLangGraphRuntime` (or `useLangGraphMessages`) to react to them:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream,
+  eventHandlers: {
+    onSubgraphValues: (namespace, values) => {
+      console.log("subgraph", namespace, "state:", values);
+    },
+    onSubgraphUpdates: (namespace, updates) => {
+      console.log("subgraph", namespace, "updates:", updates);
+    },
+    onSubgraphError: (namespace, error) => {
+      console.error("subgraph", namespace, "error:", error);
+    },
+  },
+});
+```
+
+`namespace` is a pipe-separated string like `"parent|child_agent"`. Messages emitted by a subgraph include `metadata.namespace` so you can attribute tool results to the correct sub-agent.
+
+## `useLangChainState`
+
+When using `@assistant-ui/react-langchain` (`useStreamRuntime`), the `useLangChainState` hook lets you read any key from the current LangChain/LangGraph state on the client without a separate API call:
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+
+function TodoSidebar() {
+  const todos = useLangChainState<string[]>("todos", []);
+  return <ul>{todos.map((t) => <li key={t}>{t}</li>)}</ul>;
+}
+```
+
+The second argument is an optional default value. The hook re-renders whenever the state key changes during a stream.
+
 ## Best Practices
 
-1. **Use Tools() API**: Always prefer the `Tools()` API over legacy component/hook-based registration
+1. **Pick one registration style per tool**: avoid registering the same tool through both the `Tools()` toolkit and a component-based API; both routes will register, and duplicates are rejected
 2. **Centralize Definitions**: Keep all tools in a toolkit file for easy management
 3. **Clear Descriptions**: Write descriptive tool descriptions that help the LLM understand when to use each tool
 4. **Parameter Validation**: Use Zod schemas to ensure type safety
@@ -524,9 +620,9 @@ export async function POST(req: Request) {
 8. **Performance**: Use abort signals for cancellable operations
 9. **Testing**: Test tools in isolation and with the full assistant flow
 
-## Migration from Legacy APIs
+## Switching from Component-Based to Toolkit
 
-To migrate from legacy APIs to the `Tools()` API:
+If you prefer the toolkit shape, switching is mechanical:
 
 1. **Create a toolkit object** with all your tools
 2. **Move tool definitions** from `makeAssistantTool`/`useAssistantTool` calls into the toolkit
@@ -537,7 +633,7 @@ To migrate from legacy APIs to the `Tools()` API:
 Example migration:
 
 ```tsx
-// Before (Legacy)
+// Component-based API
 const WeatherTool = makeAssistantTool({
   toolName: "getWeather",
   description: "Get weather",
@@ -554,7 +650,7 @@ function App() {
   );
 }
 
-// After (Recommended)
+// Toolkit API
 const toolkit: Toolkit = {
   getWeather: {
     description: "Get weather",