Backport: docs(zod-schema): add warning about .meta() / .describe() method chaining order (#10496)

This is an automated backport of #10452 to the release-v5.0 branch. FYI
@IdoBouskila

Co-authored-by: Ido Bouskila <[email protected]>

Author: vercel-ai-sdk[bot]

content/docs/07-reference/01-ai-sdk-core/26-zod-schema.mdx

@@ -17,6 +17,26 @@ You can use it to [generate structured data](/docs/ai-sdk-core/generating-struct
   the `zodSchema()` helper function instead.
 </Note>
 
+<Note type="warning">
+  When using `.meta()` or `.describe()` to add metadata to your Zod schemas,
+  make sure these methods are called **at the end** of the schema chain.
+  
+  metadata is attached to a specific schema
+  instance, and most schema methods (`.min()`, `.optional()`, `.extend()`, etc.)
+  return a new schema instance that does not inherit metadata from the previous one.
+  Due to Zod's immutability, metadata is only included in the JSON schema output
+  if `.meta()` or `.describe()` is the last method in the chain.
+
+```ts
+// ❌ Metadata will be lost - .min() returns a new instance without metadata
+z.string().meta({ describe: 'first name' }).min(1);
+
+// ✅ Metadata is preserved - .meta() is the final method
+z.string().min(1).meta({ describe: 'first name' });
+```
+
+</Note>
+
 ## Example with recursive schemas
 
 ```ts