chore: replace deprecated .describe() with .meta() in docs (#322)

Updates all Zod schema examples in docs to use `.meta({ description: "..." })`
instead of `.describe()`, which is the recommended approach in Zod 4+.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: oskarscholander

docs/api/ai.md

@@ -302,7 +302,7 @@ const weatherTool = toolDefinition({
   name: "getWeather",
   description: "Get the current weather for a city",
   inputSchema: z.object({
-    city: z.string().describe("City name"),
+    city: z.string().meta({ description: "City name" }),
   }),
 }).server(async ({ city }) => {
   // Implementation that fetches weather info

docs/guides/client-tools.md

@@ -65,8 +65,8 @@ export const updateUIDef = toolDefinition({
   name: "update_ui",
   description: "Update the UI with new information",
   inputSchema: z.object({
-    message: z.string().describe("Message to display"),
-    type: z.enum(["success", "error", "info"]).describe("Message type"),
+    message: z.string().meta({ description: "Message to display" }),
+    type: z.enum(["success", "error", "info"]).meta({ description: "Message type" }),
   }),
   outputSchema: z.object({
     success: z.boolean(),
@@ -77,8 +77,8 @@ export const saveToLocalStorageDef = toolDefinition({
   name: "save_to_local_storage",
   description: "Save data to browser local storage",
   inputSchema: z.object({
-    key: z.string().describe("Storage key"),
-    value: z.string().describe("Value to store"),
+    key: z.string().meta({ description: "Storage key" }),
+    value: z.string().meta({ description: "Value to store" }),
   }),
   outputSchema: z.object({
     saved: z.boolean(),

docs/guides/server-tools.md

@@ -60,7 +60,7 @@ const getUserDataDef = toolDefinition({
   name: "get_user_data",
   description: "Get user information from the database",
   inputSchema: z.object({
-    userId: z.string().describe("The user ID to look up"),
+    userId: z.string().meta({ description: "The user ID to look up" }),
   }),
   outputSchema: z.object({
     name: z.string(),
@@ -93,7 +93,7 @@ const getUserDataDef = toolDefinition({
   name: "get_user_data",
   description: "Get user information from the database",
   inputSchema: z.object({
-    userId: z.string().describe("The user ID to look up"),
+    userId: z.string().meta({ description: "The user ID to look up" }),
   }),
   outputSchema: z.object({
     name: z.string(),
@@ -118,8 +118,8 @@ const searchProductsDef = toolDefinition({
   name: "search_products",
   description: "Search for products in the catalog",
   inputSchema: z.object({
-    query: z.string().describe("Search query"),
-    limit: z.number().optional().describe("Maximum number of results"),
+    query: z.string().meta({ description: "Search query" }),
+    limit: z.number().optional().meta({ description: "Maximum number of results" }),
   }),
 });
 

docs/guides/structured-outputs.md

@@ -31,7 +31,7 @@ TanStack AI uses **Standard JSON Schema**, which means you can use any schema li
 - [Valibot](https://valibot.dev/) (via `@valibot/to-json-schema`)
 - Plain JSON Schema objects
 
-> **Note:** Refer to your schema library's documentation for details on defining schemas and using features like `.describe()` for field descriptions. TanStack AI will convert your schema to JSON Schema format automatically.
+> **Note:** Refer to your schema library's documentation for details on defining schemas and using features like `.meta()` for field descriptions. TanStack AI will convert your schema to JSON Schema format automatically.
 
 ## Basic Usage
 
@@ -44,9 +44,9 @@ import { z } from "zod";
 
 // Define your schema
 const PersonSchema = z.object({
-  name: z.string().describe("The person's full name"),
-  age: z.number().describe("The person's age in years"),
-  email: z.string().email().describe("The person's email address"),
+  name: z.string().meta({ description: "The person's full name" }),
+  age: z.number().meta({ description: "The person's age in years" }),
+  email: z.string().email().meta({ description: "The person's email address" }),
 });
 
 // Use it with chat()
@@ -112,16 +112,16 @@ recipe.instructions.map((step) => step.toUpperCase()); // string[]
 
 ## Using Field Descriptions
 
-Schema field descriptions help the AI understand what data to extract. Most schema libraries support a `.describe()` method:
+Schema field descriptions help the AI understand what data to extract. In Zod 4+, use the `.meta()` method:
 
 ```typescript
 const ProductSchema = z.object({
-  name: z.string().describe("The product name"),
-  price: z.number().describe("Price in USD"),
-  inStock: z.boolean().describe("Whether the product is currently available"),
+  name: z.string().meta({ description: "The product name" }),
+  price: z.number().meta({ description: "Price in USD" }),
+  inStock: z.boolean().meta({ description: "Whether the product is currently available" }),
   categories: z
     .array(z.string())
-    .describe("Product categories like 'electronics', 'clothing', etc."),
+    .meta({ description: "Product categories like 'electronics', 'clothing', etc." }),
 });
 ```
 
@@ -134,7 +134,7 @@ You can define deeply nested structures:
 ```typescript
 const CompanySchema = z.object({
   name: z.string(),
-  founded: z.number().describe("Year the company was founded"),
+  founded: z.number().meta({ description: "Year the company was founded" }),
   headquarters: z.object({
     city: z.string(),
     country: z.string(),
@@ -149,7 +149,7 @@ const CompanySchema = z.object({
   ),
   financials: z
     .object({
-      revenue: z.number().describe("Annual revenue in millions USD"),
+      revenue: z.number().meta({ description: "Annual revenue in millions USD" }),
       profitable: z.boolean(),
     })
     .optional(),

docs/guides/tools.md

@@ -48,7 +48,7 @@ Zod schemas provide full TypeScript type inference and runtime validation:
 import { z } from "zod";
 
 const inputSchema = z.object({
-  location: z.string().describe("City name"),
+  location: z.string().meta({ description: "City name" }),
   unit: z.enum(["celsius", "fahrenheit"]).optional(),
 });
 ```
@@ -91,7 +91,7 @@ const getWeatherDef = toolDefinition({
   name: "get_weather",
   description: "Get the current weather for a location",
   inputSchema: z.object({
-    location: z.string().describe("The city and state, e.g. San Francisco, CA"),
+    location: z.string().meta({ description: "The city and state, e.g. San Francisco, CA" }),
     unit: z.enum(["celsius", "fahrenheit"]).optional(),
   }),
   outputSchema: z.object({

docs/reference/functions/convertSchemaToJsonSchema.md

@@ -48,7 +48,7 @@ JSON Schema object that can be sent to LLM providers
 import * as z from 'zod';
 
 const zodSchema = z.object({
-  location: z.string().describe('City name'),
+  location: z.string().meta({ description: 'City name' }),
   unit: z.enum(['celsius', 'fahrenheit']).optional()
 });
 

docs/reference/interfaces/ServerTool.md

@@ -138,7 +138,7 @@ Standard JSON Schema compliant schemas are converted to JSON Schema for LLM prov
 // Using Zod v4+ schema (natively supports Standard JSON Schema)
 import { z } from 'zod';
 z.object({
-  location: z.string().describe("City name or coordinates"),
+  location: z.string().meta({ description: "City name or coordinates" }),
   unit: z.enum(["celsius", "fahrenheit"]).optional()
 })
 ```

docs/reference/interfaces/Tool.md

@@ -133,7 +133,7 @@ Standard JSON Schema compliant schemas are converted to JSON Schema for LLM prov
 // Using Zod v4+ schema (natively supports Standard JSON Schema)
 import { z } from 'zod';
 z.object({
-  location: z.string().describe("City name or coordinates"),
+  location: z.string().meta({ description: "City name or coordinates" }),
   unit: z.enum(["celsius", "fahrenheit"]).optional()
 })
 ```

docs/reference/interfaces/ToolDefinition.md

@@ -166,7 +166,7 @@ Standard JSON Schema compliant schemas are converted to JSON Schema for LLM prov
 // Using Zod v4+ schema (natively supports Standard JSON Schema)
 import { z } from 'zod';
 z.object({
-  location: z.string().describe("City name or coordinates"),
+  location: z.string().meta({ description: "City name or coordinates" }),
   unit: z.enum(["celsius", "fahrenheit"]).optional()
 })
 ```

docs/reference/interfaces/ToolDefinitionInstance.md

@@ -142,7 +142,7 @@ Standard JSON Schema compliant schemas are converted to JSON Schema for LLM prov
 // Using Zod v4+ schema (natively supports Standard JSON Schema)
 import { z } from 'zod';
 z.object({
-  location: z.string().describe("City name or coordinates"),
+  location: z.string().meta({ description: "City name or coordinates" }),
   unit: z.enum(["celsius", "fahrenheit"]).optional()
 })
 ```